documentrix 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd386c4c61e93a3c711116c94d8373b6051d43d46c7387ab86e46e139eaa8c5e
-  data.tar.gz: d4c490c4faf11f0785172cf8e2d70e53e92652edb59261f0579f6a11c3bf92a2
+  metadata.gz: 2dab47f4f45491e8341757cd3a2247c4b75f8384d7b6e4b9dab0ee0624833df6
+  data.tar.gz: '045718990a43e85783481fca6e0a3cbcbad7b059f03a03a5f3ab34391a26d952'
 SHA512:
-  metadata.gz: 6ccf9b47eeca82500116a7cacb370ba5f2981cc39815b11e7f05c1be826094c0a932ab6226a3436294941af9e63e3be7e1021061f3c4a3a9903422a9b19a9c3d
-  data.tar.gz: 2bd7415288c8a45291c669d7d7012d676770d967d4954184b309f84350e2b13dd741fea4b79130aa1f857aac288b9d4f083dee00b3011d54a15ee0a53c09672e
+  metadata.gz: 90096387422aa1fc3678968597bbcefe5cbd20460fe36b0b894c801bff71354ee9c2439d41f8c99e3c8af4c133f07103e2578eed0a2a26dc95954ed8c3eae443
+  data.tar.gz: 9a54deddc18ac3ee3b54636f529ee081d4c43f72b1e8f54546be2816fd1fd380439e62d674a5505139266c2ccde73cbeeebe6126ee894e48042e408ce8d71679

data/CHANGES.md

@@ -1,5 +1,25 @@
 # Changes
 
+## 2026-10-04 v0.8.0
+
+* Added `records(tags:, sources:)` lookup method:
+  * New `records(tags:, sources:)` facade in `documents.rb` delegating to
+    `@cache`.
+  * `Common#records` fallback implementation using `each.select` with
+    tag-intersection and source-membership filters, projected via
+    `transpose.last.to_a`.
+  * `SQLiteCache#records` override using `json_each` + `IN` for precise
+    array-element tag matching and `source IN` for multi-source filtering,
+    skipping the embedding JOIN.
+  * Added comprehensive specs for the new method across `documents_spec.rb`,
+    `memory_cache_spec.rb`, `redis_cache_spec.rb`, `sqlite_cache_spec.rb`, and
+    `interface_spec.rb`.
+* Upgraded Valkey image from **9.0.1-alpine** to **9.1.2-alpine** in
+  `docker-compose.yml`.
+* Refactored tag intersection checks in cache to use `any?`.
+* Updated `ollama` embed call expectations in `spec/documents_spec.rb` to use
+  `options: {}` instead of `options: nil`.
+
 ## 2026-09-12 v0.7.0
 
 *   `Documents#initialize`: Changed `model_options` default contract from

data/docker-compose.yml

@@ -1,6 +1,6 @@
 services:
   redis:
-    image: valkey/valkey:9.0.1-alpine
+    image: valkey/valkey:9.1.2-alpine
     restart: unless-stopped
     ports: [ "127.0.0.1:9736:6379" ]
     volumes:

data/documentrix.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: documentrix 0.7.0 ruby lib
+# stub: documentrix 0.8.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "documentrix".freeze
-  s.version = "0.7.0".freeze
+  s.version = "0.8.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -17,7 +17,7 @@ Gem::Specification.new do |s|
   s.licenses = ["MIT".freeze]
   s.rdoc_options = ["--title".freeze, "Documentrix - Ruby library for embedding vector database".freeze, "--main".freeze, "README.md".freeze]
   s.required_ruby_version = Gem::Requirement.new(">= 3.1".freeze)
-  s.rubygems_version = "4.0.17".freeze
+  s.rubygems_version = "4.0.20".freeze
   s.summary = "Ruby library for embedding vector database".freeze
   s.test_files = ["spec/documentrix/documents/cache/interface_spec.rb".freeze, "spec/documentrix/documents/cache/memory_cache_spec.rb".freeze, "spec/documentrix/documents/cache/redis_cache_spec.rb".freeze, "spec/documentrix/documents/cache/sqlite_cache_spec.rb".freeze, "spec/documentrix/documents/splitters/character_spec.rb".freeze, "spec/documentrix/documents/splitters/semantic_spec.rb".freeze, "spec/documents_spec.rb".freeze, "spec/spec_helper.rb".freeze, "spec/utils/colorize_texts_spec.rb".freeze, "spec/utils/digests_spec.rb".freeze, "spec/utils/tags_spec.rb".freeze]
 

data/lib/documentrix/documents/cache/common.rb

@@ -70,7 +70,7 @@ module Documentrix::Documents::Cache::Common
     tags    = Documentrix::Utils::Tags.new(Array(tags)).to_a
     records = self
     if tags.present?
-      records = records.select { |_key, record| (tags & record.tags).size >= 1 }
+      records = records.select { |_key, record| (tags & record.tags).any? }
     end
 
     needle_norm = norm(needle)
@@ -88,6 +88,27 @@ module Documentrix::Documents::Cache::Common
     max_records ? records.take(max_records) : records
   end
 
+  # Returns records filtered by tag and/or source, without vector search.
+  #
+  # At least one of +tags:+ or +sources:+ should be given to avoid a full
+  # collection scan. The +tags:+ parameter accepts a single tag string or an
+  # array of tags (OR semantics — a record matching *any* given tag is
+  # returned).
+  #
+  # @param tags [String, Array<String>, nil] tag name(s) to filter by
+  # @param sources [String, Array<String>, nil] source(s) to filter by
+  #   (exact match — a record from *any* given source is returned)
+  #
+  # @return [Array<Documentrix::Documents::Record>] matching records
+  def records(tags: nil, sources: nil)
+    tags    = Documentrix::Utils::Tags.new(Array(tags)).to_a
+    sources = Array(sources)
+    each.select do |_key, record|
+      (tags.empty? || (tags & record.tags).any?) &&
+        (sources.empty? || sources.include?(record.source))
+    end.transpose.last.to_a
+  end
+
   # Returns a set of unique tags found in the cache records.
   #
   # This method iterates through all records in the cache and collects unique
@@ -112,7 +133,7 @@ module Documentrix::Documents::Cache::Common
   # @return [self] self
   def clear_for_tags(tags)
     each do |key, record|
-      if (tags & record.tags.to_a).size >= 1
+      if (tags & record.tags.to_a).any?
         delete(unpre(key))
       end
     end

data/lib/documentrix/documents/cache/sqlite_cache.rb

@@ -341,6 +341,50 @@ class Documentrix::Documents::Cache::SQLiteCache
     vector
   end
 
+  # Returns records filtered by tag and/or source, without vector search.
+  #
+  # This is a high-performance override for SQLite that uses `json_each`
+  # for precise array-element matching, avoiding the embedding JOIN and
+  # the Ruby-side post-filter needed by the `LIKE '%tag%'` substring hack.
+  #
+  # @param tags [String, Array<String>, nil] tag name(s) to filter by
+  #   (OR semantics — a record matching any given tag is returned)
+  # @param sources [String, Array<String>, nil] source(s) to filter by
+  #   (exact match — a record from *any* given source is returned)
+  #
+  # @return [Array<Documentrix::Documents::Record>] matching records
+  def records(tags: nil, sources: nil)
+    tags    = Documentrix::Utils::Tags.new(tags).to_a
+    sources = Array(sources)
+
+    where = ['key LIKE ?']
+    args  = [ start_with_prefix ]
+
+    unless tags.empty?
+      where << "EXISTS (SELECT 1 FROM json_each(tags) " \
+        "WHERE json_each.value IN (%s)) " % (%w[ ? ] * tags.size).join(?,)
+      args.concat(tags)
+    end
+
+    unless sources.empty?
+      where << "source IN (%s) " % (%w[ ? ] * sources.size).join(?,)
+      args.concat(sources)
+    end
+
+    where = where.map { '(%s)' % _1 }
+
+    execute(
+      "SELECT key, text, source, tags, digest " \
+      "FROM records WHERE #{where.join(' AND ')}",
+      args
+    ).map do |key, text, source, tags, digest|
+      convert_value_to_record(
+        key: unpre(key), text:, source:,
+        tags: JSON(tags.to_s).to_a, digest:
+      )
+    end
+  end
+
   # The find_records_for_tags method filters records based on the provided tags.
   #
   # @param tags [ Array ] an array of tag names
@@ -362,7 +406,7 @@ class Documentrix::Documents::Cache::SQLiteCache
     }, [ start_with_prefix ])
     if tags_filter
       records = records.select { |key, tags, embedding_id|
-        (tags_filter & JSON(tags.to_s).to_a).size >= 1
+        (tags_filter & JSON(tags.to_s).to_a).any?
       }
     end
     records

data/lib/documentrix/documents.rb

@@ -413,6 +413,17 @@ class Documentrix::Documents
     @cache.each_source.to_a
   end
 
+  # Returns records filtered by tag and/or source, without vector search.
+  #
+  # @param tags [String, Array<String>, nil] tag name(s) to filter by
+  # @param sources [String, Array<String>, nil] source(s) to filter by
+  #   (exact match — a record from *any* given source is returned)
+  #
+  # @return [Array<Documentrix::Documents::Record>] matching records
+  def records(tags: nil, sources: nil)
+    @cache.records(tags:, sources:)
+  end
+
  # The each_record method iterates over all records stored in the cache.
  #
  # @yield [record] The record being iterated over.

data/lib/documentrix/version.rb

@@ -1,6 +1,6 @@
 module Documentrix
   # Documentrix version
-  VERSION         = '0.7.0'
+  VERSION         = '0.8.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/spec/documentrix/documents/cache/interface_spec.rb

@@ -58,6 +58,9 @@ describe 'Documentrix::Documents::Cache Interface' do
 
       expect(cache).to respond_to(:clear)
       expect(cache.method(:clear).owner).to eq Documentrix::Documents::Cache::Common
+
+      expect(cache).to respond_to(:records)
+      expect(cache.method(:records).owner).to eq Documentrix::Documents::Cache::Common
     end
   end
 
@@ -127,6 +130,9 @@ describe 'Documentrix::Documents::Cache Interface' do
       expect(cache).to respond_to(:clear)
       expect(cache.method(:clear).owner).to eq Documentrix::Documents::Cache::Common
 
+      expect(cache).to respond_to(:records)
+      expect(cache.method(:records).owner).to eq Documentrix::Documents::Cache::Common
+
       # Redis-specific methods
       expect(cache).to respond_to(:redis)
       expect(cache.method(:redis).owner).to eq Documentrix::Documents::RedisCache
@@ -205,6 +211,9 @@ describe 'Documentrix::Documents::Cache Interface' do
 
       expect(cache).to respond_to(:find_records_for_tags)
       expect(cache.method(:find_records_for_tags).owner).to eq Documentrix::Documents::Cache::SQLiteCache
+
+      expect(cache).to respond_to(:records)
+      expect(cache.method(:records).owner).to eq Documentrix::Documents::Cache::SQLiteCache
     end
   end
 end

data/spec/documentrix/documents/cache/memory_cache_spec.rb

@@ -197,4 +197,45 @@ describe Documentrix::Documents::MemoryCache do
     expect(cache.source_exist?('s1', digest: 'd1', operator: '!=')).to be false
     expect(cache.source_exist?('s1', digest: 'd2', operator: '!=')).to be true
   end
+
+  describe '#records' do
+    before do
+      cache['a'] = Documentrix::Documents::Record[text: 'a', source: 's1', tags: ['x', 'y'], embedding: [0.1]]
+      cache['b'] = Documentrix::Documents::Record[text: 'b', source: 's1', tags: ['y'], embedding: [0.1]]
+      cache['c'] = Documentrix::Documents::Record[text: 'c', source: 's2', tags: ['x'], embedding: [0.1]]
+    end
+
+    it 'filters by a single tag' do
+      result = cache.records(tags: 'x')
+      expect(result.map(&:text)).to match_array(%w[a c])
+    end
+
+    it 'filters by multiple tags with OR semantics' do
+      result = cache.records(tags: %w[x y])
+      expect(result.map(&:text)).to match_array(%w[a b c])
+    end
+
+    it 'filters by source' do
+      result = cache.records(sources: 's2')
+      expect(result.map(&:text)).to eq ['c']
+    end
+
+    it 'filters by tag and source' do
+      result = cache.records(tags: 'x', sources: 's1')
+      expect(result.map(&:text)).to eq ['a']
+    end
+
+    it 'filters by multiple sources (OR)' do
+      result = cache.records(sources: %w[s1 s2])
+      expect(result.map(&:text)).to match_array(%w[a b c])
+    end
+
+    it 'returns all records when no filter is given' do
+      expect(cache.records.map(&:text)).to match_array(%w[a b c])
+    end
+
+    it 'returns empty array for non-matching tag' do
+      expect(cache.records(tags: 'z')).to eq []
+    end
+  end
 end

data/spec/documentrix/documents/cache/redis_cache_spec.rb

@@ -185,6 +185,97 @@ describe Documentrix::Documents::RedisCache do
       expect(cache.source_exist?('s1', digest: 'd2')).to be false
     end
 
+    it 'can filter records by tag' do
+      expect(redis).to receive(:scan_each).with(match: "#{prefix}*").
+        and_yield("#{prefix}foo").and_yield("#{prefix}bar")
+      expect(redis).to receive(:get).with("#{prefix}foo").
+        and_return(JSON(text: 'a', tags: ['x']))
+      expect(redis).to receive(:get).with("#{prefix}bar").
+        and_return(JSON(text: 'b', tags: ['y']))
+
+      results = cache.records(tags: 'x')
+      expect(results.map(&:text)).to eq ['a']
+    end
+
+    it 'can filter records by source' do
+      expect(redis).to receive(:scan_each).with(match: "#{prefix}*").
+        and_yield("#{prefix}foo").and_yield("#{prefix}bar")
+      expect(redis).to receive(:get).with("#{prefix}foo").
+        and_return(JSON(text: 'a', source: 's1'))
+      expect(redis).to receive(:get).with("#{prefix}bar").
+        and_return(JSON(text: 'b', source: 's2'))
+
+      results = cache.records(sources: 's1')
+      expect(results.map(&:text)).to eq ['a']
+    end
+
+    it 'can filter records by tag and source' do
+      expect(redis).to receive(:scan_each).with(match: "#{prefix}*").
+        and_yield("#{prefix}foo").and_yield("#{prefix}bar")
+        .and_yield("#{prefix}baz")
+      expect(redis).to receive(:get).with("#{prefix}foo").
+        and_return(JSON(text: 'a', source: 's1', tags: ['x']))
+      expect(redis).to receive(:get).with("#{prefix}bar").
+        and_return(JSON(text: 'b', source: 's1', tags: ['y']))
+      expect(redis).to receive(:get).with("#{prefix}baz").
+        and_return(JSON(text: 'c', source: 's2', tags: ['x']))
+
+      results = cache.records(tags: 'x', sources: 's1')
+      expect(results.map(&:text)).to eq ['a']
+    end
+
+    it 'can filter records by multiple sources' do
+      expect(redis).to receive(:scan_each).with(match: "#{prefix}*").
+        and_yield("#{prefix}foo").and_yield("#{prefix}bar")
+        .and_yield("#{prefix}baz")
+      expect(redis).to receive(:get).with("#{prefix}foo").
+        and_return(JSON(text: 'a', source: 's1'))
+      expect(redis).to receive(:get).with("#{prefix}bar").
+        and_return(JSON(text: 'b', source: 's2'))
+      expect(redis).to receive(:get).with("#{prefix}baz").
+        and_return(JSON(text: 'c', source: 's3'))
+
+      results = cache.records(sources: %w[ s1 s2 ])
+      expect(results.map(&:text)).to match_array %w[ a b ]
+    end
+
+    it 'can filter records by multiple tags (OR)' do
+      expect(redis).to receive(:scan_each).with(match: "#{prefix}*").
+        and_yield("#{prefix}foo").and_yield("#{prefix}bar")
+        .and_yield("#{prefix}baz")
+      expect(redis).to receive(:get).with("#{prefix}foo").
+        and_return(JSON(text: 'a', tags: ['x']))
+      expect(redis).to receive(:get).with("#{prefix}bar").
+        and_return(JSON(text: 'b', tags: ['y']))
+      expect(redis).to receive(:get).with("#{prefix}baz").
+        and_return(JSON(text: 'c', tags: ['z']))
+
+      results = cache.records(tags: %w[ x z ])
+      expect(results.map(&:text)).to match_array %w[ a c ]
+    end
+
+    it 'returns all records when no filter given' do
+      expect(redis).to receive(:scan_each).with(match: "#{prefix}*").
+        and_yield("#{prefix}foo").and_yield("#{prefix}bar")
+      expect(redis).to receive(:get).with("#{prefix}foo").
+        and_return(JSON(text: 'a'))
+      expect(redis).to receive(:get).with("#{prefix}bar").
+        and_return(JSON(text: 'b'))
+
+      results = cache.records
+      expect(results.map(&:text)).to match_array %w[ a b ]
+    end
+
+    it 'only returns records under current prefix' do
+      expect(redis).to receive(:scan_each).with(match: "#{prefix}*").
+        and_yield("#{prefix}foo")
+      expect(redis).to receive(:get).with("#{prefix}foo").
+        and_return(JSON(text: 'a'))
+
+      results = cache.records
+      expect(results.map(&:text)).to eq ['a']
+    end
+
     describe '#collections' do
       it 'extracts unique collection names from keys' do
         expect(redis).to receive(:scan_each).with(match: "#{prefix}*").and_yield(

data/spec/documentrix/documents/cache/sqlite_cache_spec.rb

@@ -378,4 +378,62 @@ describe Documentrix::Documents::SQLiteCache do
       expect(cache.collections('test-')).to eq []
     end
   end
+
+  describe '#records' do
+    before do
+      cache['a'] = test_value.merge(text: 'a', source: 's1', tags: %w[ x ])
+      cache['b'] = test_value.merge(text: 'b', source: 's1', tags: %w[ y ])
+      cache['c'] = test_value.merge(text: 'c', source: 's2', tags: %w[ x z ])
+    end
+
+    it 'can filter records by tag' do
+      results = cache.records(tags: 'x')
+      expect(results.map(&:text)).to match_array %w[ a c ]
+    end
+
+    it 'does not match tags by substring' do
+      # 'c' is not a tag, and 'x' should not match 'x'-ish substrings
+      expect(cache.records(tags: 'c').map(&:text)).to be_empty
+    end
+
+    it 'can filter records by source' do
+      results = cache.records(sources: 's1')
+      expect(results.map(&:text)).to match_array %w[ a b ]
+    end
+
+    it 'can filter records by tag and source' do
+      results = cache.records(tags: 'x', sources: 's1')
+      expect(results.map(&:text)).to eq ['a']
+    end
+
+    it 'can filter records by multiple sources (OR)' do
+      results = cache.records(sources: %w[s1 s2])
+      expect(results.map(&:text)).to match_array %w[a b c]
+    end
+
+    it 'can filter records by multiple tags (OR)' do
+      results = cache.records(tags: %w[ y z ])
+      expect(results.map(&:text)).to match_array %w[ b c ]
+    end
+
+    it 'returns all records when no filter given' do
+      results = cache.records
+      expect(results.map(&:text)).to match_array %w[ a b c ]
+    end
+
+    it 'returns records without an embedding' do
+      record = cache.records(tags: 'x').first
+      expect(record).to be_a Documentrix::Documents::Record
+      expect(record.embedding).to be_nil
+    end
+
+    it 'is isolated to the current prefix' do
+      cache2 = cache.dup
+      cache2.prefix = 'other-'
+      cache2['d'] = test_value.merge(text: 'd', source: 's9', tags: %w[ x ])
+
+      expect(cache.records(tags: 'x').map(&:text)).to match_array %w[ a c ]
+      expect(cache2.records(tags: 'x').map(&:text)).to eq ['d']
+    end
+  end
 end

data/spec/documents_spec.rb

@@ -21,7 +21,7 @@ describe Documentrix::Documents do
 
   it 'texts can be added to it' do
     expect(ollama).to receive(:embed).
-      with(model:, input: %w[ foo bar ], options: nil).
+      with(model:, input: %w[ foo bar ], options: {}).
       and_return(double(embeddings: [ [ 0.1 ], [ 0.2 ] ]))
     expect(documents.add(%w[ foo bar ])).to eq documents
     expect(documents.exist?('foo')).to eq true
@@ -31,7 +31,7 @@ describe Documentrix::Documents do
 
   it 'a text can be added to it' do
     expect(ollama).to receive(:embed).
-      with(model:, input: %w[ foo ], options: nil).
+      with(model:, input: %w[ foo ], options: {}).
       and_return(double(embeddings: [ [ 0.1 ] ]))
     expect(documents << 'foo').to eq documents
     expect(documents.exist?('foo')).to eq true
@@ -41,7 +41,7 @@ describe Documentrix::Documents do
 
   it 'a text with can be added to it' do
     expect(ollama).to receive(:embed).
-      with(model:, input: %w[ foo ], options: nil).
+      with(model:, input: %w[ foo ], options: {}).
       and_return(double(embeddings: [ [ 0.1 ] ]))
     expect_any_instance_of(Documentrix::Utils::Tags).to\
       receive(:add).with('bar.rb', source: '/foo/bar.rb')
@@ -53,11 +53,11 @@ describe Documentrix::Documents do
 
   it 'can find strings' do
     expect(ollama).to receive(:embed).
-      with(model:, input: [ 'foo' ], options: nil).
+      with(model:, input: [ 'foo' ], options: {}).
       and_return(double(embeddings: [ [ 0.1 ] ]))
     expect(documents << 'foo').to eq documents
     expect(ollama).to receive(:embed).
-      with(model:, input: 'foo', options: nil).
+      with(model:, input: 'foo', options: {}).
       and_return(double(embeddings: [ [ 0.1 ] ]))
     records = documents.find('foo')
     expect(records).to eq [
@@ -68,16 +68,16 @@ describe Documentrix::Documents do
 
   it 'can find only tagged strings' do
     expect(ollama).to receive(:embed).
-      with(model:, input: [ 'foo' ], options: nil).
+      with(model:, input: [ 'foo' ], options: {}).
       and_return(double(embeddings: [ [ 0.1 ] ]))
     expect(documents.add('foo', tags: %w[ test ])).to eq documents
     expect(ollama).to receive(:embed).
-      with(model:, input: 'foo', options: nil).
+      with(model:, input: 'foo', options: {}).
       and_return(double(embeddings: [ [ 0.1 ] ]))
     records = documents.find('foo', tags: %w[ nix ])
     expect(records).to eq []
     expect(ollama).to receive(:embed).
-      with(model:, input: 'foo', options: nil).
+      with(model:, input: 'foo', options: {}).
       and_return(double(embeddings: [ [ 0.1 ] ]))
     records = documents.find('foo', tags: %w[ test ])
     expect(records).to eq [
@@ -88,15 +88,15 @@ describe Documentrix::Documents do
 
   it 'can find strings conditionally' do
     expect(ollama).to receive(:embed).
-      with(model:, input: [ 'foobar' ], options: nil).
+      with(model:, input: [ 'foobar' ], options: {}).
       and_return(double(embeddings: [ [ 0.01 ] ]))
     expect(ollama).to receive(:embed).
-      with(model:, input: [ 'foo' ], options: nil).
+      with(model:, input: [ 'foo' ], options: {}).
       and_return(double(embeddings: [ [ 0.1 ] ]))
     expect(documents << 'foobar').to eq documents
     expect(documents << 'foo').to eq documents
     expect(ollama).to receive(:embed).at_least(:once).
-      with(model:, input: 'foo', options: nil).
+      with(model:, input: 'foo', options: {}).
       and_return(double(embeddings: [ [ 0.1 ] ]))
     records = documents.find_where('foo', text_count: 1)
     expect(records).to eq [
@@ -117,7 +117,7 @@ describe Documentrix::Documents do
   context 'it uses cache' do
     before do
       allow(ollama).to receive(:embed).
-        with(model:, input: %w[ foo ], options: nil).
+        with(model:, input: %w[ foo ], options: {}).
         and_return(double(embeddings: [ [ 0.1 ] ]))
     end
 
@@ -143,7 +143,7 @@ describe Documentrix::Documents do
 
     it 'can clear texts with tags' do
       expect(ollama).to receive(:embed).
-        with(model:, input: %w[ bar ], options: nil).
+        with(model:, input: %w[ bar ], options: {}).
         and_return(double(embeddings: [ [ 0.1 ] ]))
       expect(documents.add('foo', tags: %w[ test ])).to eq documents
       expect(documents.add('bar', tags: %w[ test2 ])).to eq documents
@@ -234,6 +234,49 @@ describe Documentrix::Documents do
       expect(documents.each_record).to be_a Enumerator
       expect(documents.each_record.map(&:text)).to match_array %w[ foo bar ]
     end
+
+    it 'can retrieve records filtered by tag' do
+      allow(ollama).to receive(:embed).and_return(double(embeddings: [ [ 0.1 ] ]))
+      documents.add('foo', tags: %w[ test ])
+      documents.add('bar', tags: %w[ other ])
+      expect(documents.records(tags: 'test').map(&:text)).to eq %w[ foo ]
+    end
+
+    it 'can retrieve records matching any of multiple tags' do
+      allow(ollama).to receive(:embed).and_return(double(embeddings: [ [ 0.1 ] ]))
+      documents.add('foo', tags: %w[ a ])
+      documents.add('bar', tags: %w[ b ])
+      documents.add('baz', tags: %w[ c ])
+      expect(documents.records(tags: %w[ a c ]).map(&:text)).to match_array(%w[ foo baz ])
+    end
+
+    it 'can retrieve records filtered by source' do
+      allow(ollama).to receive(:embed).and_return(double(embeddings: [ [ 0.1 ] ]))
+      documents.add('foo', source: 's1')
+      documents.add('bar', source: 's2')
+      expect(documents.records(sources: 's1').map(&:text)).to eq %w[ foo ]
+    end
+
+    it 'can retrieve records filtered by tag and source' do
+      allow(ollama).to receive(:embed).and_return(double(embeddings: [ [ 0.1 ] ]))
+      documents.add('foo', tags: %w[ test ], source: 's1')
+      documents.add('bar', tags: %w[ test ], source: 's2')
+      expect(documents.records(tags: 'test', sources: 's1').map(&:text)).to eq %w[ foo ]
+    end
+
+    it 'can retrieve records filtered by multiple sources (OR)' do
+      allow(ollama).to receive(:embed).and_return(double(embeddings: [ [ 0.1 ] ]))
+      documents.add('foo', source: 's1')
+      documents.add('bar', source: 's2')
+      documents.add('baz', source: 's3')
+      expect(documents.records(sources: %w[ s1 s3 ]).map(&:text)).to match_array(%w[ foo baz ])
+    end
+
+    it 'returns empty records when no records match' do
+      allow(ollama).to receive(:embed).and_return(double(embeddings: [ [ 0.1 ] ]))
+      documents.add('foo', tags: %w[ test ], source: 's1')
+      expect(documents.records(sources: 's2')).to eq []
+    end
   end
 
   context 'source management' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: documentrix
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Florian Frank
@@ -319,7 +319,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ruby library for embedding vector database
 test_files: