documentrix 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdd19b49af74153cf419d6ace3a2d05879c6ceb57d90e5651b777d18ca96f2b7
-  data.tar.gz: 4936bad8197cb4243a0cef32154fc11aba073b41da1e58709767e5d4e58aac96
+  metadata.gz: c76bf8eb224b18de775f6c7652cde2dcf4409423f79b2006a7e2c50f158d2769
+  data.tar.gz: c59dac8defeea81cae51ada232c3778d8ba95a0cc6c3afc19595309cc33d5a83
 SHA512:
-  metadata.gz: f334e64d609f86d32aa0524b535c2649e14f6e7a6793973fa231e1ae6d81148dd957e9095423494555591a36471b574c696f2e69882742110191e7e99b4254bf
-  data.tar.gz: 0ef7210bcdb325d19ab5415d319a5ea45c3449a9a0a892b1eac2c34006ad55ef545b5b89d98d5a57ce5afe0f18cbc9c707adf6c21ddfb3d8e20061439c60cb53
+  metadata.gz: 27758319636b90ff0772ed866187bd2cef9673e203e79fc6ff72bd53ad2b43906029b011a738eb5e695f744e4c2cf733cef1ba46640488df91b23f314f3c6d80
+  data.tar.gz: 9c115acc0ec7e43eb7330f0422a69d4f0d8afea592947b994382d40d73f54502b143d43b939b924dcfdd053ea824847f044052aef89176f646ab9e1108c592e2

data/.utilsrc

@@ -0,0 +1,107 @@
+# vim: set ft=ruby:
+
+search do
+  prune_dirs /\A(\.svn|\.git|\.terraform|CVS|tmp|coverage|corpus|pkg|\.yardoc|doc)\z/
+  skip_files /(\A\.|\.sw[pon]\z|\.(log|fnm|jpg|jpeg|png|pdf|svg)\z|\A(tags|cscope\.out)\z|~\z)/i
+end
+
+discover do
+  prune_dirs /\A(\.svn|\.git|\.terraform|\.yardoc|CVS|tmp|coverage|corpus|pkg|\.yardoc|doc)\z/
+  skip_files /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
+  index_expire_after 3_600
+end
+
+strip_spaces do
+  prune_dirs /\A(\..*|CVS|pkg|\.yardoc)\z/
+  skip_files /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
+end
+
+probe do
+  test_framework :rspec
+end
+
+ssh_tunnel do
+  terminal_multiplexer :tmux
+  login_session "/home/#{ENV['USER']}"
+end
+
+classify do
+  shift_path_by_default 1
+end
+
+code_indexer do
+  verbose false
+
+  gems = %w[
+    all_images
+    amatch
+    base64
+    bigdecimal
+    complex_config
+    connection_pool
+    date
+    debug
+    diff-lcs
+    docile
+    documentrix
+    erb
+    excon
+    fileutils
+    gem_hadar
+    infobar
+    io-console
+    irb
+    json
+    kramdown
+    kramdown-ansi
+    kramdown-parser-gfm
+    logger
+    mize
+    more_math
+    net-http
+    nokogiri
+    numo-narray-alt
+    ollama-ruby
+    openssl
+    ostruct
+    pp
+    prettyprint
+    prism
+    psych
+    racc
+    rake
+    rdoc
+    readline
+    redis
+    redis-client
+    reline
+    rexml
+    rspec
+    rspec-core
+    rspec-expectations
+    rspec-mocks
+    rspec-support
+    search_ui
+    shellwords
+    simplecov
+    simplecov-html
+    simplecov_json_formatter
+    sqlite-vec
+    sqlite3
+    stringio
+    sync
+    term-ansicolor
+    terminal-table
+    tins
+    tsort
+    unicode-display_width
+    unicode-emoji
+    uri
+    yaml
+    yard
+  ]
+
+  paths {
+    %w[ lib ] + gems.map { `bundle show #{it}` }.map(&:chomp)
+  }
+end

data/CHANGES.md

@@ -1,5 +1,33 @@
 # Changes
 
+## 2026-03-29 v0.1.0
+
+- Added `Documentrix::Documents#rename_collection` to rename a collection and
+  delegate key moving to the cache.
+- Extended `Documentrix::Documents::Cache::Common#pre` and `#unpre` to accept
+  an optional `prefix` argument.
+- Implemented `Documentrix::Documents::Cache::MemoryCache#move_prefix`,
+  `RedisCache#move_prefix`, and `SQLiteCache#move_prefix` for atomic key
+  mass‑move operations.
+- Updated unit tests to cover the new rename and prefix‑moving functionality.
+- Switched to `GemHadar::SimpleCov` for test coverage.
+- Removed the `redis_backed_memory_cache` implementation and its spec.
+- Added a `.utilsrc` configuration file defining blocks for `search`,
+  `discover`, `strip_spaces`, `probe`, `ssh_tunnel`, `classify`, and
+  `code_indexer`.
+- Reordered Docker `apk add` commands and added friendly echo messages during
+  image build and test phases.
+- Added `fail_fast: true` flag to the Docker file definition.
+- Added interface spec for cache implementations (`memory`, `Redis`, `SQLite`).
+- Included `Set` requirement for older Ruby versions.
+- Removed unused expiry functionality from `RedisCache`.
+- Refactored cache system to use explicit inheritance, moving common methods
+  into `Documentrix::Documents::Cache::Common` and renaming `clear` to
+  `clear_all_with_prefix`.
+- Updated documentation with detailed RDoc comments.
+- Updated CI configuration to use `bundle exec` and cleaned up `Gemfile.lock`.
+- Added `changelog` configuration in `Rakefile` to support `CHANGES.md`.
+
 ## 2025-12-20 v0.0.4
 
 - Added `openssl-dev` to the package list in `.all_images.yml` for Docker

data/Rakefile

@@ -24,6 +24,10 @@ GemHadar do
      '.rspec'
   readme     'README.md'
 
+  changelog do
+    filename 'CHANGES.md'
+  end
+
   required_ruby_version  '>= 3.1'
 
   dependency 'infobar',         '~> 0.9'
@@ -36,7 +40,7 @@ GemHadar do
   dependency 'redis',           '~> 5.0'
   dependency 'more_math',       '~> 1.1'
 
-  development_dependency 'all_images', '~> 0.9'
+  development_dependency 'all_images', '~> 0.12'
   development_dependency 'rspec',      '~> 3.2'
   development_dependency 'kramdown',   '~> 2.0'
   development_dependency 'debug'

data/docker-compose.yml

@@ -1,6 +1,6 @@
 services:
   redis:
-    image: valkey/valkey:8.1.1-alpine
+    image: valkey/valkey:9.0.1-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.0.4 ruby lib
+# stub: documentrix 0.1.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "documentrix".freeze
-  s.version = "0.0.4".freeze
+  s.version = "0.1.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -11,20 +11,20 @@ Gem::Specification.new do |s|
   s.date = "1980-01-02"
   s.description = "The Ruby library, Documentrix, is designed to provide a way to build and\nquery vector databases for applications in natural language processing\n(NLP) and large language models (LLMs). It allows users to store and\nretrieve dense vector embeddings for text strings.\n".freeze
   s.email = "flori@ping.de".freeze
-  s.extra_rdoc_files = ["README.md".freeze, "lib/documentrix.rb".freeze, "lib/documentrix/documents.rb".freeze, "lib/documentrix/documents/cache/common.rb".freeze, "lib/documentrix/documents/cache/memory_cache.rb".freeze, "lib/documentrix/documents/cache/records.rb".freeze, "lib/documentrix/documents/cache/redis_backed_memory_cache.rb".freeze, "lib/documentrix/documents/cache/redis_cache.rb".freeze, "lib/documentrix/documents/cache/sqlite_cache.rb".freeze, "lib/documentrix/documents/splitters/character.rb".freeze, "lib/documentrix/documents/splitters/semantic.rb".freeze, "lib/documentrix/utils.rb".freeze, "lib/documentrix/utils/colorize_texts.rb".freeze, "lib/documentrix/utils/math.rb".freeze, "lib/documentrix/utils/tags.rb".freeze, "lib/documentrix/version.rb".freeze]
-  s.files = [".envrc".freeze, ".yardopts".freeze, "CHANGES.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "docker-compose.yml".freeze, "documentrix.gemspec".freeze, "lib/documentrix.rb".freeze, "lib/documentrix/documents.rb".freeze, "lib/documentrix/documents/cache/common.rb".freeze, "lib/documentrix/documents/cache/memory_cache.rb".freeze, "lib/documentrix/documents/cache/records.rb".freeze, "lib/documentrix/documents/cache/redis_backed_memory_cache.rb".freeze, "lib/documentrix/documents/cache/redis_cache.rb".freeze, "lib/documentrix/documents/cache/sqlite_cache.rb".freeze, "lib/documentrix/documents/splitters/character.rb".freeze, "lib/documentrix/documents/splitters/semantic.rb".freeze, "lib/documentrix/utils.rb".freeze, "lib/documentrix/utils/colorize_texts.rb".freeze, "lib/documentrix/utils/math.rb".freeze, "lib/documentrix/utils/tags.rb".freeze, "lib/documentrix/version.rb".freeze, "redis/redis.conf".freeze, "spec/assets/embeddings.json".freeze, "spec/documentrix/documents/cache/memory_cache_spec.rb".freeze, "spec/documentrix/documents/cache/redis_backed_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/tags_spec.rb".freeze]
+  s.extra_rdoc_files = ["README.md".freeze, "lib/documentrix.rb".freeze, "lib/documentrix/documents.rb".freeze, "lib/documentrix/documents/cache/common.rb".freeze, "lib/documentrix/documents/cache/memory_cache.rb".freeze, "lib/documentrix/documents/cache/records.rb".freeze, "lib/documentrix/documents/cache/redis_cache.rb".freeze, "lib/documentrix/documents/cache/sqlite_cache.rb".freeze, "lib/documentrix/documents/splitters/character.rb".freeze, "lib/documentrix/documents/splitters/semantic.rb".freeze, "lib/documentrix/utils.rb".freeze, "lib/documentrix/utils/colorize_texts.rb".freeze, "lib/documentrix/utils/math.rb".freeze, "lib/documentrix/utils/tags.rb".freeze, "lib/documentrix/version.rb".freeze]
+  s.files = [".envrc".freeze, ".utilsrc".freeze, ".yardopts".freeze, "CHANGES.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "docker-compose.yml".freeze, "documentrix.gemspec".freeze, "lib/documentrix.rb".freeze, "lib/documentrix/documents.rb".freeze, "lib/documentrix/documents/cache/common.rb".freeze, "lib/documentrix/documents/cache/memory_cache.rb".freeze, "lib/documentrix/documents/cache/records.rb".freeze, "lib/documentrix/documents/cache/redis_cache.rb".freeze, "lib/documentrix/documents/cache/sqlite_cache.rb".freeze, "lib/documentrix/documents/splitters/character.rb".freeze, "lib/documentrix/documents/splitters/semantic.rb".freeze, "lib/documentrix/utils.rb".freeze, "lib/documentrix/utils/colorize_texts.rb".freeze, "lib/documentrix/utils/math.rb".freeze, "lib/documentrix/utils/tags.rb".freeze, "lib/documentrix/version.rb".freeze, "redis/redis.conf".freeze, "spec/assets/embeddings.json".freeze, "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/tags_spec.rb".freeze]
   s.homepage = "https://github.com/flori/documentrix".freeze
   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.2".freeze
+  s.rubygems_version = "4.0.8".freeze
   s.summary = "Ruby library for embedding vector database".freeze
-  s.test_files = ["spec/documentrix/documents/cache/memory_cache_spec.rb".freeze, "spec/documentrix/documents/cache/redis_backed_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/tags_spec.rb".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/tags_spec.rb".freeze]
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.10".freeze])
-  s.add_development_dependency(%q<all_images>.freeze, ["~> 0.9".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, [">= 2.17.0".freeze])
+  s.add_development_dependency(%q<all_images>.freeze, ["~> 0.12".freeze])
   s.add_development_dependency(%q<rspec>.freeze, ["~> 3.2".freeze])
   s.add_development_dependency(%q<kramdown>.freeze, ["~> 2.0".freeze])
   s.add_development_dependency(%q<debug>.freeze, [">= 0".freeze])

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

@@ -1,5 +1,18 @@
+# Common interface for document caches
+#
+# This module defines the standard interface that all document cache
+# implementations must adhere to. It provides shared functionality for managing
+# cached document embeddings, including methods for setting, retrieving, and
+# deleting cache entries, as well as querying and filtering cached data based
+# on tags and similarity searches.
+#
+# The module includes methods for prefix management, collection enumeration,
+# tag extraction, and cache clearing operations, ensuring consistent behavior
+# across different cache backends such as
+# memory, Redis, and SQLite.
 module Documentrix::Documents::Cache::Common
   include Documentrix::Utils::Math
+  include Enumerable
 
   # The initialize method sets up the Documentrix::Documents::Cache instance's
   # by setting its prefix attribute to the given value.
@@ -27,17 +40,100 @@ module Documentrix::Documents::Cache::Common
   # Returns a string representing the given `key` prefixed with the defined
   # prefix.
   #
-  # @param key [String] the key to join with the prefix
-  # @return [String] the joined string of prefix and key
-  def pre(key)
-    [ @prefix, key ].join
+  # @param key [String] the key to prefix
+  # @param prefix [String] the prefix to use (defaults to the cache's prefix)
+  # @return [String] the prefixed key
+  def pre(key, prefix: @prefix)
+    [ prefix, key ].join
   end
 
   # Returns a string with the prefix removed from the given `key`.
   #
   # @param key [String] the input string containing the prefix.
+  # @param prefix [String] the prefix to use (defaults to the cache's prefix)
   # @return [String] the input string without the prefix.
-  def unpre(key)
-    key.sub(/\A#@prefix/, '')
+  def unpre(key, prefix: @prefix)
+    key.sub(/\A#{prefix}/, '')
+  end
+
+  # The find_records method finds records that match the given needle and
+  # tags.
+  #
+  # @param needle [ Array ] an array containing the embedding vector
+  # @param tags [ String, Array ] a string or array of strings representing the tags to search for
+  # @param max_records [ Integer ] the maximum number of records to return
+  #
+  # @yield [ record ]
+  #
+  # @return [ Array<Documentrix::Documents::Records> ] an array containing the matching records
+  def find_records(needle, tags: nil, max_records: nil)
+    tags    = Documentrix::Utils::Tags.new(Array(tags)).to_a
+    records = self
+    if tags.present?
+      records = records.select { |_key, record| (tags & record.tags).size >= 1 }
+    end
+    needle_norm = norm(needle)
+    records     = records.sort_by { |key, record|
+      record.key        = key
+      record.similarity = cosine_similarity(
+        a: needle,
+        b: record.embedding,
+        a_norm: needle_norm,
+        b_norm: record.norm,
+      )
+    }
+    records.transpose.last&.reverse.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
+  # tags from each record's tags collection. It constructs a new
+  # Documentrix::Utils::Tags object containing all the unique tags encountered.
+  #
+  # @return [Documentrix::Utils::Tags] a set of unique tags from all records in
+  #   the cache
+  def tags
+    each_with_object(Documentrix::Utils::Tags.new) do |(_, record), t|
+      record.tags.each do |tag|
+        t.add(tag, source: record.source)
+      end
+    end
+  end
+
+  # The clear_for_tags method removes all records from the cache that have tags
+  # matching any of the provided tags.
+  #
+  # @param tags [Array<String>] an array of tag names to filter records by
+  #
+  # @return [self] self
+  def clear_for_tags(tags)
+    each do |key, record|
+      if (tags & record.tags.to_a).size >= 1
+        delete(unpre(key))
+      end
+    end
+    self
+  end
+
+  # The clear method removes cached records based on the provided tags or
+  # clears all records with the current prefix.
+  #
+  # When tags are provided, it removes only the records that have matching
+  # tags. If no tags are provided, it removes all records that have keys
+  # starting with the current prefix.
+  #
+  # @param tags [NilClass, Array<String>] an array of tag names to filter
+  #   records by, or nil to clear all records
+  #
+  # @return [self] returns the cache instance for method chaining
+  def clear(tags: nil)
+    tags = Documentrix::Utils::Tags.new(tags).to_a
+    if tags.present?
+      clear_for_tags(tags)
+    else
+      clear_all_with_prefix
+    end
+    self
   end
 end

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

@@ -1,5 +1,17 @@
 require 'documentrix/documents/cache/common'
 
+# MemoryCache is an in-memory cache implementation for document embeddings.
+#
+# This class provides a cache store for document embeddings using a hash-based
+# in-memory storage mechanism. It implements the common cache interface
+# defined in Documentrix::Documents::Cache::Common and supports operations
+# such as setting, retrieving, and deleting cached entries, as well as
+# iterating over cached items.
+#
+# The cache uses a prefix to namespace keys and supports clearing entries
+# based on prefixes or specific tags. It is designed to be used as a
+# temporary storage mechanism during processing and is not persistent
+# across application restarts.
 class Documentrix::Documents::MemoryCache
   include Documentrix::Documents::Cache::Common
 
@@ -59,32 +71,48 @@ class Documentrix::Documents::MemoryCache
     count
   end
 
-  # The clear method removes all records from the cache that have keys starting
-  # with the prefix `prefix`.
+  # The clear_all_with_prefix method removes all records from the cache that
+  # have keys starting with the prefix `prefix`.
   #
   # @return [ Documentrix::Documents::MemoryCache ] self
-  def clear
+  def clear_all_with_prefix
     @data.delete_if { |key, _| key.start_with?(@prefix) }
     self
   end
 
+  # Move all keys that start with +old_prefix+ into a new prefix.
+  #
+  # This helper is used when a collection is renamed.  It iterates over all
+  # cached entries, selects those whose keys start with *old_prefix*, strips
+  # that prefix, then re‑inserts the entry with the *new_prefix* instead.
+  #
+  # @param old_prefix [String] The prefix to look for on existing keys.
+  # @param new_prefix [String] The prefix that will replace *old_prefix*.
+  # @return [Documentrix::Documents::MemoryCache] Returns `self` to allow
+  #   chaining.
+  def move_prefix(old_prefix, new_prefix)
+    new_data = @data.dup
+    full_each do |key, value|
+      key.start_with?(old_prefix) or next
+      unpre_key = unpre(key, prefix: old_prefix)
+      new_data[pre(unpre_key, prefix: new_prefix)] = new_data.delete(key)
+    end
+    @data.replace(new_data)
+    self
+  end
+
   # The each method iterates over the cache's keys and values under a given
   # prefix `prefix`.
   #
   # @yield [key, value] Each key-value pair in the cache
-  #
-  # @return [void]
   def each(&block)
     @data.select { |key,| key.start_with?(@prefix) }.each(&block)
   end
-  include Enumerable
 
   # The full_each method iterates over the data hash and yields each key-value
   # pair to the given block regardless of the prefix `prefix`.
   #
   # @yield [key, value] Each key-value pair in the data hash
-  #
-  # @return [void]
   def full_each(&block)
     @data.each(&block)
   end

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

@@ -1,4 +1,18 @@
+# Module for cache record definitions used in Documentrix document caching.
+#
+# This module provides the Record class and RedisFullEach module for managing
+# cached document embeddings and their associated metadata in the Documentrix
+# library's caching system.
 module Documentrix::Documents::Cache::Records
+  # A record class for caching document embeddings and their associated
+  # metadata.
+  #
+  # This class extends JSON::GenericObject and is used to represent cached
+  # document entries in the Documentrix library. It stores text content,
+  # embedding vectors, normalization values, source information, and tags
+  # associated with each document record. The class provides methods for string
+  # representation, tag handling, and equality comparison based on text
+  # content.
   class Record < JSON::GenericObject
     # The initialize method sets default values for the text and norm
     # attributes.
@@ -41,94 +55,4 @@ module Documentrix::Documents::Cache::Records
 
     alias inspect to_s
   end
-
-  module RedisFullEach
-    # The full_each method iterates over all records in the cache and yields
-    # them to the block.
-    #
-    # @yield [ key, value ] where key is the record's key and value is the record itself
-    def full_each(&block)
-      redis.scan_each(match: [ Documentrix::Documents, ?* ] * ?-) do |key|
-        value = redis.get(key) or next
-        value = JSON(value, object_class: Documentrix::Documents::Record)
-        block.(key, value)
-      end
-    end
-  end
-
-  module FindRecords
-    # The find_records method finds records that match the given needle and
-    # tags.
-    #
-    # @param needle [ Array ] an array containing the embedding vector
-    # @param tags [ String, Array ] a string or array of strings representing the tags to search for
-    # @param max_records [ Integer ] the maximum number of records to return
-    #
-    # @yield [ record ]
-    #
-    # @return [ Array<Documentrix::Documents::Records> ] an array containing the matching records
-    def find_records(needle, tags: nil, max_records: nil)
-      tags    = Documentrix::Utils::Tags.new(Array(tags)).to_a
-      records = self
-      if tags.present?
-        records = records.select { |_key, record| (tags & record.tags).size >= 1 }
-      end
-      needle_norm = norm(needle)
-      records     = records.sort_by { |key, record|
-        record.key        = key
-        record.similarity = cosine_similarity(
-          a: needle,
-          b: record.embedding,
-          a_norm: needle_norm,
-          b_norm: record.norm,
-        )
-      }
-      records.transpose.last&.reverse.to_a
-    end
-  end
-
-  module Tags
-    # The clear method removes all records that match the given tags from the
-    # cache.
-    #
-    # @param tags [ Array<String> ] an array of tag names
-    #
-    # @example
-    #   documents.clear(tags: %w[ foo bar ])
-    #
-    # @return [ self ]
-    def clear(tags: nil)
-      tags = Documentrix::Utils::Tags.new(tags).to_a
-      if tags.present?
-        if respond_to?(:clear_for_tags)
-          clear_for_tags(tags)
-        else
-          each do |key, record|
-            if (tags & record.tags.to_a).size >= 1
-              delete(unpre(key))
-            end
-          end
-        end
-      else
-        super()
-      end
-      self
-    end
-
-    # The tags method returns an array of unique tags from all records.
-    #
-    # @return [Documentrix::Utils::Tags] An instance of
-    #         Documentrix::Utils::Tags containing the unique tags.
-    def tags
-      if defined? super
-        super
-      else
-        each_with_object(Documentrix::Utils::Tags.new) do |(_, record), t|
-          record.tags.each do |tag|
-            t.add(tag, source: record.source)
-          end
-        end
-      end
-    end
-  end
 end

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

@@ -1,6 +1,18 @@
 require 'documentrix/documents/cache/common'
 require 'redis'
 
+# RedisCache is a cache implementation that uses Redis for storing document
+# embeddings and related metadata.
+#
+# This class provides a persistent cache storage solution for document
+# embeddings, leveraging Redis's capabilities to store both the embedding
+# vectors and associated text data, tags, and source information. It supports
+# efficient vector similarity searches through Redis-based operations.
+#
+# @example
+#   cache = Documentrix::Documents::RedisCache.new(prefix: 'docs-', url: 'redis://localhost:6379')
+#   cache['key'] = { text: 'example', embedding: [0.1, 0.2, 0.3] }
+#   value = cache['key']
 class Documentrix::Documents::RedisCache
   include Documentrix::Documents::Cache::Common
 
@@ -11,11 +23,10 @@ class Documentrix::Documents::RedisCache
   # @param [String] prefix the string to be used as the prefix for this cache
   # @param [String] url the URL of the Redis server (default: ENV['REDIS_URL'])
   # @param [Class] object_class the class of objects stored in Redis (default: nil)
-  # @param [Integer] ex the expiration time in seconds (default: nil)
-  def initialize(prefix:, url: ENV['REDIS_URL'], object_class: nil, ex: nil)
+  def initialize(prefix:, url: ENV['REDIS_URL'], object_class: nil)
     super(prefix:)
     url or raise ArgumentError, 'require redis url'
-    @url, @object_class, @ex = url, object_class, ex
+    @url, @object_class = url, object_class
   end
 
   attr_reader :object_class # the class of objects stored in the cache
@@ -35,7 +46,7 @@ class Documentrix::Documents::RedisCache
   def [](key)
     value = redis.get(pre(key))
     unless value.nil?
-      object_class ? JSON(value, object_class:) : JSON(value)
+      object_class ? JSON.parse(value, object_class:) : JSON.parse(value)
     end
   end
 
@@ -53,28 +64,13 @@ class Documentrix::Documents::RedisCache
   #
   # @param [String] key the string representation of the key
   # @param [Object] value the object to be stored under the given key
-  # @option ex [Integer] ex the expiration time in seconds (default: nil)
   #
   # @return [Object] self
-  def set(key, value, ex: nil)
-    ex ||= @ex
-    if !ex.nil? && ex < 1
-      redis.del(pre(key))
-    else
-      redis.set(pre(key), JSON.generate(value), ex:)
-    end
+  def set(key, value)
+    redis.set(pre(key), JSON.generate(value))
     value
   end
 
-  # The ttl method returns the time-to-live (TTL) value for the given key
-  #
-  # @param [String] key the string representation of the key
-  #
-  # @return [Integer, nil] the TTL value if it exists in Redis, or nil otherwise
-  def ttl(key)
-    redis.ttl(pre(key))
-  end
-
   # The key? method checks if the given key exists in Redis by calling the
   # redis.exists? method
   #
@@ -105,12 +101,33 @@ class Documentrix::Documents::RedisCache
     s
   end
 
-  # The clear method removes all key-value pairs associated with the given
-  # prefix from this cache instance.
+  # The clear_all_with_prefix method removes all key-value pairs associated
+  # with the given prefix from this cache instance.
   #
   # @return [Documentrix::Documents::RedisCache] self
-  def clear
+  def clear_all_with_prefix
     redis.scan_each(match: "#@prefix*") { |key| redis.del(key) }
+    defined? super and super
+    self
+  end
+
+  # Renames all keys that start with <tt>old_prefix</tt> to use
+  # <tt>new_prefix</tt>. The method iterates over every affected key,
+  # reconstructs the new key name (preserving the part of the key that follows
+  # the old prefix), writes the value under the new name, and deletes the old
+  # key.
+  #
+  # @param old_prefix [String] The prefix that currently identifies the target keys.
+  # @param new_prefix [String] The prefix that should replace <tt>old_prefix</tt>.
+  #
+  # @return [self] The cache instance, facilitating method chaining.
+  def move_prefix(old_prefix, new_prefix)
+    full_each(prefix: '') do |key, value|
+      key.start_with?(old_prefix) or next
+      unpre_key = unpre(key, prefix: old_prefix)
+      redis.set(pre(unpre_key, prefix: new_prefix), JSON.generate(value))
+      redis.del(key)
+    end
     self
   end
 
@@ -121,8 +138,23 @@ class Documentrix::Documents::RedisCache
   #
   # @return [self] self
   def each(&block)
+    block or return enum_for(__method__)
+
     redis.scan_each(match: "#@prefix*") { |key| block.(key, self[unpre(key)]) }
     self
   end
-  include Enumerable
+
+  # The full_each method iterates over all records in the cache and yields
+  # them to the block.
+  #
+  # @yield [ key, value ] where key is the record's key and value is the record itself
+  def full_each(prefix: 'Documents-', &block)
+    block or return enum_for(__method__, prefix:)
+
+    redis.scan_each(match: prefix + ?*) do |key|
+      value = redis.get(key) or next
+      value = object_class ? JSON.parse(value, object_class:) : JSON.parse(value)
+      block.(key, value)
+    end
+  end
 end