emb 0.4.0.pre1 → 0.4.0.pre4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 646506ae908e1f9db100c67c6d4e20dc6c6fc84e9d2d2a62c7954385ff632d73
-  data.tar.gz: 07e42cf06b265483d14899ad8607909ad8caa99243e28bd7fe66dfad6eef1496
+  metadata.gz: 0c6f451b27da29d343a893e88a8ae949620e33213941a785088d0e66f1cbe8ab
+  data.tar.gz: 7eb7bc8fa4069bedc853d1580c5504a1a1fbbdff432ff458f61152487199de78
 SHA512:
-  metadata.gz: 0ea5a3f7613be7280da47b7e52ebcff8b7773ef33ebbdcdbaa231e28084b8e4b3b12755be415b965b82ce395ea252c1dbf7592a4981740e2ba45b67e97338d49
-  data.tar.gz: 869f1f0df61b44fc09aa6ce95b4b04bbcf0de1542f2697594160e16baf977dc6707df7a7a6da77a0e68be3d1f199c77f2cac171e0a41cabdf467c8958a352e89
+  metadata.gz: 94e720e10c56ccca0655c7dab9e28ac71d1731a4da5206664338be49de3dd2756f2acc56aa938a0b949f22dbe38927e2231abfee44cdf5339646079d8bf01fd0
+  data.tar.gz: 115a9d1814d895c856f39f6a557625cdb19abb59628dca39e314f35ace1c97c171c5a44c3c06c53500a6dee4332602f43bc4da04f6dabf0da053524ca43b6030

data/Gemfile

@@ -9,6 +9,11 @@ gem 'redis-client'
 gem 'rake', require: false
 gem 'rspec', require: false
 
+# Development-only: the Railtie integration suite boots a real Rails app so the
+# real middleware-stack objects and boot order are exercised. Rails is never a
+# runtime dependency of the gem. Select a line with RAILS_VERSION.
+gem 'rails', ENV.fetch('RAILS_VERSION', '~> 8.0'), require: false
+
 gem 'rubocop', require: false
 gem 'rubocop-rake', require: false
 gem 'rubocop-rspec', require: false

data/README.md

@@ -78,7 +78,7 @@ coalescing with `lazy: :multi` or concurrent fan-out with `lazy: :batch` — glo
 can take over a second of inference on a shared CPU, and redis-client's silent default is
 1.0s — a slower reply times out. The gem therefore defaults to an explicit 10s timeout
 and `reconnect_attempts: 0`: a failing batch fails closed after one attempt and raises
-`Emb::ServerError` (see [Lazy execution modes](#lazy-execution-modes)). Set
+`Emb::ServerError` (see [Lazy batching](#lazy-batching)). Set
 `Emb.configure { |c| c.reconnect_attempts = 2 }` and redis-client re-sends
 **connection and protocol failures** up to that many extra times before the batch fails
 closed — each re-send re-runs server inference, so keep the budget small. Operation
@@ -291,6 +291,28 @@ exceptions (`RedisClient::CommandError`): read-only parameters (`listen`, `tls_*
 `models`), invalid values, and `NOAUTH` on password-protected servers are not
 swallowed.
 
+### Cache lifecycle commands
+
+When server-side caching is enabled, the Ruby client exposes the lifecycle
+commands on module, instance, pooled, and round-robin clients:
+
+```ruby
+Emb.cache_flush             # all models; => removed entry count
+Emb.cache_flush(:minilm)    # one model; => removed entry count
+Emb.save_cache              # => "OK" once the background save is accepted
+
+Emb.stats[:cache_snapshot_in_progress] # 0 or 1
+Emb.server_info(:cache)                # completion, failure, restore limits
+```
+
+Snapshot persistence is configured on the server with `cache_file`,
+`cache_load`, `cache_save`, `cache_save_on_shutdown`, `cache_restore_limit`,
+`cache_restore_reserve`, and `cache_save_rate_limit`. Automatic saves keep
+serving inference and control commands while encoding and I/O run in the
+background. Snapshot files include original input text and embeddings; use
+protected/encrypted storage where appropriate and treat them as disposable
+warm-start data rather than a durable database.
+
 ## Usage
 
 ### Single text
@@ -307,6 +329,32 @@ client = Emb.new(url: "redis://localhost:6379")
 result = client[:minilm]["hello world"]
 ```
 
+### VALUE format (RESP decimal reply)
+
+By default the server replies with the compact float32 binary wire and the gem
+unpacks it. Pass `format: :values` to send the RedisAI-style `VALUES` keyword
+and get the server's self-describing envelope back: `dtype`, `shape`, and the
+embedding values as decimal floats (the float64 widening the server stores, so
+`unpack` is not needed). Single texts return the envelope with flat `values`;
+multiple texts group the values per text (rows of `shape`).
+
+```ruby
+Emb[:minilm]["hello world", format: :values]
+# => { dtype: "FLOAT", shape: [1, 384], values: [0.0123, -0.0456, ...] }
+
+Emb[:minilm]["hello", "world", format: :values]
+# => { dtype: "FLOAT", shape: [2, 384], values: [[...], [...]] }
+```
+
+The batch loaders accept the same keyword; mixed formats within one batch
+raise `ArgumentError`.
+
+> **RESP3 note:** the server emits the decimal values as typed RESP3 doubles when
+> the connection negotiated `HELLO 3` and as decimal bulk strings otherwise.
+> The gem speaks RESP2 (binary default, decimal `values` opt-in) and does not
+> parse RESP3 replies itself — connect with a RESP3-capable client to use the
+> typed doubles on the wire.
+
 ### Multiple texts
 
 ```ruby
@@ -336,17 +384,37 @@ client.multi do |m|
 end
 ```
 
-### Lazy execution modes
+### Script replies
 
-Embed-call behavior is governed by a single `lazy` mode — `false` (default, eager),
-`:multi` (defer and coalesce into one `EMB` for a single model / one `EMB.MULTI` for mixed scopes, serial), or `:batch` (defer and execute
-the coalesced chunk shares **concurrently**). The three are mutually exclusive.
+`Emb.eval` / `Emb.evalsha` run a Lua script against a model (KEYS = texts,
+ARGV = args) and parse replies through the RESP grammar — hashes, arrays,
+strings, errors. Unlike the embed path, a scripted reply has no fixed shape,
+so packed vectors are **not** auto-decoded: a `float32_bytes` reply comes back
+as the raw bulk String. Decode it per call with the `decode:` keyword:
 
-| mode | `Emb[:model][text]` | execution |
-|---|---|---|
-| `false` (default) | immediate `EMB` round trip | serial, per call |
-| `:multi` | deferred → coalesces into one `EMB` (single model) or `EMB.MULTI` (mixed) | serial, one command at a time |
-| `:batch` | deferred → coalesces into `EMB`/`EMB.MULTI` chunks | **concurrent** — chunk shares run in parallel |
+```ruby
+sha = client.script.load(:siglip2, siglip_source)
+
+# decode: :f32 — the reply is a packed float32 vector (or a numeric array)
+vec = client.evalsha(:siglip2, sha, ["a photo of a cat"], ["normalize"], decode: :f32)
+# => [0.0123, -0.0456, ...]  768 floats
+
+# multi-text replies decode each element
+vecs = client.evalsha(:siglip2, sha, ["a", "b"], ["normalize"], decode: :f32)
+# => [[0.0123, ...], [-0.0456, ...]]
+
+# decode: {field => :f32} — structured replies decode a named field
+out = client.evalsha(:siglip2, sha, ["a"], ["normalize"], decode: { embedding: :f32 })
+# => {"dim" => 768, "embedding" => [0.0123, ...]}
+```
+
+`decode:` defaults to `nil` (no decoding, exactly today's behavior). Supported
+modes are `:f32` and `{field => :f32}`; anything else, or a reply that is not
+actually a float vector / hash at the decodable position, raises
+`ArgumentError`. A raw bulk can always be decoded by hand with
+`reply.unpack("e*")`.
+
+### Lazy batching
 
 In `:batch` mode the shares fan out across the configured instances (one share per
 instance when the share count allows) or across the instance's pool connections when a
@@ -465,13 +533,22 @@ If your Gemfile loads `emb` before Rails is required (non-standard boot order),
 guarded railtie require in `emb.rb` is skipped — add `require "emb/railtie"` in
 `config/application.rb` right after `require "rails/all"` (or in an initializer).
 
-The middleware is also safe to mount manually in any Rack app (the Railtie
-skips insertion when it is already present):
+The middleware is also safe to mount manually in any Rack app. In a Rails app,
+set the opt-out as well so the Railtie does not add a second copy:
 
 ```ruby
+# config/application.rb
+config.emb.middleware = false
+```
+
+```ruby
+# wherever you build the stack
 use Emb::Middleware
 ```
 
+A duplicate mount is harmless — clearing the per-thread scope is idempotent — but
+the opt-out keeps the stack clean and makes the intended wiring explicit.
+
 The scope is cleared even when the app raises, and a fresh scope starts
 automatically with the next request. Loaders created but never used within a
 request are dropped — the create-then-consume contract applies per request.

data/lib/emb/batch.rb

@@ -3,6 +3,7 @@
 require 'batch_loader'
 require 'redis_client'
 require_relative 'batch_dispatch'
+require_relative 'values_batch'
 
 module Emb
   extend BatchDispatch
@@ -45,11 +46,17 @@ module Emb
     # explicit receiver.
     private(*BatchDispatch.instance_methods(false))
 
-    def build_batch_loader(client, model, text)
+    def build_batch_loader(client, model, text, format: :binary)
+      unless %i[binary values].include?(format)
+        raise ArgumentError, "unknown format #{format.inspect} (expected :binary or :values)"
+      end
+
       # default_value []: an item whose batch failed (fail-closed) resolves to
       # an empty vector collection instead of nil, so resolver methods like
       # `loader.sum` do not blow up with NoMethodError-on-nil.
-      BatchLoader.for([client, model, text]).batch(default_value: [], key: BATCH_KEY, &BATCH_BLOCK)
+      # Items carry [client, model, text, format] so the dispatch knows how to
+      # shape and parse the reply.
+      BatchLoader.for([client, model, text, format]).batch(default_value: [], key: BATCH_KEY, &BATCH_BLOCK)
     end
 
     # Removes every pending item of the batch scope. batch-loader prunes

data/lib/emb/batch_dispatch.rb

@@ -11,17 +11,37 @@ module Emb
     # the command may have been sent are terminal and propagate so the forcing
     # thread can fail closed.
     def dispatch_slice(client, slice)
-      models = slice.map { |_, model, _| model }.uniq
+      models = slice.map { |_, model, _, _| model }.uniq
       args = models.size == 1 ? same_model_args(slice, models.first) : mixed_model_args(slice)
       Array(client.send_command(*args))
     end
 
     def same_model_args(slice, model)
-      ['EMB', model.to_s, *slice.flat_map { |_, _, text| Array(text) }]
+      texts = slice.flat_map { |_, _, text, _| Array(text) }
+      if slice_format(slice) == :values
+        ['EMB', model.to_s, 'VALUES', *texts]
+      else
+        ['EMB', model.to_s, *texts]
+      end
     end
 
     def mixed_model_args(slice)
-      ['EMB.MULTI', *slice.flat_map { |_, model, text| Array(text).flat_map { |t| [model.to_s, t] } }]
+      pairs = slice.flat_map { |_, model, text, _| Array(text).flat_map { |t| [model.to_s, t] } }
+      if slice_format(slice) == :values
+        ['EMB.MULTI', 'VALUES', *pairs]
+      else
+        ['EMB.MULTI', *pairs]
+      end
+    end
+
+    # slice_format: the batch item layout is [client, model, text, format];
+    # items created before the format slot existed default to :binary.
+    def slice_format(slice)
+      formats = slice.map { |item| item[3] }.uniq
+      if formats.size > 1
+        raise ArgumentError, "cannot mix :binary and :values formats in one batch"
+      end
+      formats.first || :binary
     end
 
     # Maps a slice's reply entries onto its items in deferral order. Runs on
@@ -31,14 +51,18 @@ module Emb
     # from a client-raised ProtocolError so it is not counted as a transport
     # retry).
     def resolve_slice(loader, slice, results)
-      expected = slice.sum { |_, _, text| Array(text).size }
+      if slice_format(slice) == :values
+        return ValuesBatch.resolve(loader, slice, results)
+      end
+
+      expected = slice.sum { |_, _, text, _| Array(text).size }
       unless results.size >= expected
         raise ShortReplyError, "expected #{expected} reply entries, got #{results.size}"
       end
 
       offset = 0
       slice.each do |item|
-        _, _, text = item
+        _, _, text, _ = item
         texts = Array(text)
         values = entry_values(results, offset, texts)
         offset += texts.size

data/lib/emb/commands.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require_relative 'script_reply_decode'
+
 module Emb
   # Server-status and runtime-config command wrappers. They only depend on
   # #send_command, so they live in this module (included into Emb::Client)
   # rather than growing the client class.
   module Commands
+    include ScriptReplyDecode
+
     # EMB.STATS as a Symbol-keyed Hash. No client-side type layer: values are
     # exactly what the RESP decoder returned (Integer where the server sends
     # RESP integers, String otherwise).
@@ -19,8 +23,101 @@ module Emb
       parse_info(send_command('INFO', *sections.map(&:to_s)))
     end
 
+    # Evaluate a script against a model (EMB.EVAL). texts become the script's
+    # KEYS, args its ARGV. Replies are typed per the reply grammar: hash
+    # replies (flat field/value pair arrays under RESP2) become Ruby Hashes,
+    # nested values recurse. decode: opt-in float decoding — see
+    # parse_script_reply (decode: :f32 or decode: {field => :f32}).
+    def eval(model, script, texts, args = [], decode: nil)
+      texts = Array(texts)
+      schema = normalize_decode(decode)
+      reply = send_command('EMB.EVAL', model.to_s, script, texts.size, *texts.map(&:to_s), *args.map(&:to_s))
+      parse_script_reply(reply, multi: texts.size > 1, decode: schema)
+    end
+
+    # Evaluate a previously loaded script by SHA1 (EMB.EVSHA). See #eval.
+    def evalsha(model, sha, texts, args = [], decode: nil)
+      texts = Array(texts)
+      schema = normalize_decode(decode)
+      reply = send_command('EMB.EVSHA', model.to_s, sha, texts.size, *texts.map(&:to_s), *args.map(&:to_s))
+      parse_script_reply(reply, multi: texts.size > 1, decode: schema)
+    end
+
+    # EMB.SCRIPT subcommands: a small command object so the surface reads
+    # naturally (script.load / script.exists / script.flush).
+    def script
+      @script ||= ScriptCommands.new(self)
+    end
+
+    # EMB.SCRIPT LOAD/EXISTS/FLUSH.
+    class ScriptCommands
+      def initialize(client)
+        @client = client
+      end
+
+      # Compile, cache, and return the script's SHA1 for the model.
+      def load(model, source)
+        @client.send_command('EMB.SCRIPT', 'LOAD', model.to_s, source)
+      end
+
+      # Whether each SHA is cached for the model.
+      def exists(model, *shas)
+        @client.send_command('EMB.SCRIPT', 'EXISTS', model.to_s, *shas.map(&:to_s)).map { |flag| flag == 1 }
+      end
+
+      # Clear the model's cached scripts, or all models when omitted.
+      def flush(model = nil)
+        args = ['EMB.SCRIPT', 'FLUSH']
+        args << model.to_s if model
+        @client.send_command(*args)
+      end
+    end
+
+    # Remove all cached embeddings, or only entries belonging to +model+.
+    # Returns the server's integer removed-entry count.
+    def cache_flush(model = nil)
+      args = ['EMB.CACHE.FLUSH']
+      args << model.to_s unless model.nil?
+      send_command(*args)
+    end
+
+    # Ask the server to start an asynchronous cache snapshot. Completion and
+    # failures are observable through #stats or #server_info(:cache).
+    def save_cache
+      send_command('EMB.SAVE')
+    end
+
     private
 
+    # Converts a scripted reply (single value, or an array of per-text values
+    # for multi-text calls) through the hash grammar: a flat field/value pair
+    # array becomes a Hash, recursively. Pure even-length string lists are
+    # indistinguishable from two-field hashes on the RESP2 wire, so scripts
+    # that must return them should nest them (wrap the list in a table).
+    #
+    # decode is the normalized (see normalize_decode) opt-in float decoding:
+    #   nil                        → no decoding, parsing exactly as before
+    #   :f32                       → each value position is unpack('e*')'d when
+    #                                it is a packed float bulk; numeric arrays
+    #                                pass through unchanged (element types kept)
+    #   {field => :f32, ...}       → after hash parsing, the named field(s) of
+    #                                each hash reply decode as :f32 (fields
+    #                                absent from a reply are left untouched)
+    def parse_script_reply(reply, multi:, decode: nil)
+      parsed = (multi ? reply : [reply]).map { |v| script_hash(v) }
+      decoded = apply_decode(parsed, decode)
+      multi ? decoded : decoded.first
+    end
+
+    def script_hash(value)
+      return value unless value.is_a?(Array) && value.size.even?
+
+      pairs = value.each_slice(2).to_a
+      return value unless pairs.all? { |field, _| field.is_a?(String) }
+
+      pairs.to_h { |field, val| [field, script_hash(val)] }
+    end
+
     # Parse Redis INFO section text into a nested Hash:
     #   {Server: {redis_version: "0.2.4", uptime_secs: "7"}, Cache: {…}, …}
     # Section names and keys are Symbols; values pass through as the server

data/lib/emb/proxy.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'values_reply'
+
 module Emb
   class Proxy
     attr_reader :name
@@ -9,8 +11,20 @@ module Emb
       @name = name
     end
 
-    def [](text, *texts)
-      return Emb.build_batch_loader(@client, @name, texts.empty? ? text : [text, *texts]) if @client.lazy?
+    # Queries the model for one or more texts. format: :binary (default)
+    # returns the float32-unpacked vectors from the compact BLOB wire;
+    # format: :values sends the VALUES keyword and returns the decoded
+    # envelope — a Hash with dtype:/shape:/values: (Flats, flat for a single
+    # text, grouped per text when several are requested).
+    def [](text, *texts, format: :binary)
+      format = normalize_format(format)
+      if @client.lazy?
+        return Emb.build_batch_loader(@client, @name, texts.empty? ? text : [text, *texts], format: format)
+      end
+
+      if format == :values
+        return values_query(text, texts)
+      end
 
       set = Array(@client.send_command('EMB', @name.to_s, text, *texts))
       result = set.map { |entry| entry.unpack('e*') }
@@ -23,5 +37,23 @@ module Emb
     def inspect
       "#<Emb::Proxy #{@name}>"
     end
+
+    private
+
+    def normalize_format(format)
+      unless %i[binary values].include?(format)
+        raise ArgumentError, "unknown format #{format.inspect} (expected :binary or :values)"
+      end
+
+      format
+    end
+
+    def values_query(text, texts)
+      reply = @client.send_command('EMB', @name.to_s, 'VALUES', text, *texts)
+      envelope = Emb::ValuesReply.parse(reply)
+      return envelope if texts.empty?
+
+      envelope.merge(values: Emb::ValuesReply.rows(envelope[:shape], envelope[:values]))
+    end
   end
 end

data/lib/emb/railtie.rb

@@ -13,9 +13,13 @@ if defined?(Rails::Railtie)
       config.emb.middleware = true
       config.emb.job_middleware = true
 
+      # Insertion is unconditional (opt-out excepted): during initialization the
+      # stack is a Rails::Configuration::MiddlewareStackProxy, which records
+      # operations but cannot be inspected. Duplicate insertion is safe because
+      # Emb::BatchScope clearing is idempotent, so manual mounts use the opt-out
+      # instead of relying on detection.
       initializer 'emb.middleware' do |app|
         next if config.emb.middleware == false
-        next if app.middleware.include?(Emb::Middleware)
 
         app.middleware.use Emb::Middleware
       end

data/lib/emb/script_reply_decode.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Emb
+  # Opt-in float decoding for scripted replies — the decode: keyword on
+  # Emb::Commands#eval / #evalsha. Kept out of the Commands module so the
+  # command surface stays small. decode: is validated (normalize_decode) before
+  # any command is sent, then applied after reply parsing.
+  module ScriptReplyDecode
+    private
+
+    # Validates an (un-normalized) decode option and canonicalizes it. Raises
+    # ArgumentError for unknown modes so callers fail before any command is
+    # sent. nil and an empty hash both mean "no decoding".
+    def normalize_decode(decode)
+      case decode
+      when nil, :f32
+        decode
+      when Hash
+        schema = decode.each_with_object({}) do |(field, mode), acc|
+          unless mode == :f32
+            raise ArgumentError, "unsupported decode mode #{mode.inspect} for field #{field.inspect} (supported: :f32)"
+          end
+
+          acc[field.to_s] = :f32
+        end
+        schema.empty? ? nil : schema
+      else
+        raise ArgumentError, "unsupported decode mode #{decode.inspect} (supported: :f32 or {field => :f32})"
+      end
+    end
+
+    # Applies a normalized decode to the parsed (script_hash'ed) reply array.
+    def apply_decode(parsed, decode)
+      return parsed if decode.nil?
+
+      case decode
+      when :f32
+        parsed.each_with_index.map { |v, i| decode_f32(v, position(i)) }
+      when Hash
+        parsed.each_with_index.map { |v, i| decode_hash_fields(v, decode, position(i)) }
+      end
+    end
+
+    def position(index)
+      index.zero? ? 'the reply' : "element #{index + 1}"
+    end
+
+    # decode: :f32 — a float32-packed bulk unpacks to floats; a numeric array
+    # (the pre-float32_bytes reply style) passes through unchanged; anything
+    # else is a contract mismatch and raises.
+    def decode_f32(value, where)
+      case value
+      when String
+        unless (value.bytesize % 4).zero?
+          raise ArgumentError,
+                "decode :f32: #{where} is a #{value.bytesize}-byte bulk, not a multiple of 4 — not a float32 vector"
+        end
+
+        value.unpack('e*')
+      when Array
+        return value if value.all?(Numeric)
+
+        raise ArgumentError, "decode :f32: #{where} is an array of non-numbers, not a float vector"
+      else
+        raise ArgumentError,
+              "decode :f32: #{where} is a #{value.class}, expected a float32-packed bulk or a numeric array"
+      end
+    end
+
+    # decode: {field => :f32} — the reply (or each per-text reply) must be a
+    # hash; present fields decode as :f32, absent fields stay untouched.
+    def decode_hash_fields(value, schema, where)
+      unless value.is_a?(Hash)
+        raise ArgumentError, "decode #{schema.inspect}: #{where} is a #{value.class}, expected a hash reply"
+      end
+
+      schema.each_key do |field|
+        next unless value.key?(field)
+
+        value[field] = decode_f32(value[field], "field #{field.inspect} of #{where}")
+      end
+      value
+    end
+  end
+end

data/lib/emb/values_batch.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative 'values_reply'
+
+module Emb
+  # VALUES-format batch resolution for the deferred path. Split out of
+  # BatchDispatch so both modules stay under the Metrics rubric.
+  module ValuesBatch
+    module_function
+
+    # Resolves a VALUES reply onto the slice's items. Single-model slices get
+    # ONE envelope reply carrying every text's flattened values (row-major),
+    # so the rows are re-sliced per item; mixed-model slices get per-pair
+    # envelopes and map one row each. Failures stay nil, mirroring the BLOB
+    # path's MGET semantics.
+    def resolve(loader, slice, results)
+      if single_model?(slice)
+        rows = envelope_rows(results)
+        expect_rows!(slice, rows.size)
+        assign_rows(loader, slice, rows)
+      else
+        resolve_entries(loader, slice, results)
+      end
+    end
+
+    def single_model?(slice)
+      slice.map { |item| item[1] }.uniq.size == 1
+    end
+
+    def envelope_rows(results)
+      envelope = Emb::ValuesReply.parse(rehydrate_envelope(results))
+      Emb::ValuesReply.rows(envelope[:shape], envelope[:values])
+    end
+
+    # Under RESP3, redis-client decodes the server's single-model VALUES map
+    # into a Ruby Hash, but dispatch_slice wraps every reply in Array(), which
+    # turns that Hash into an array of [key, value] pairs. Rehydrate those
+    # pairs back into a Hash so parse sees a real envelope; RESP2 flat pair
+    # arrays (top-level strings) pass through untouched.
+    def rehydrate_envelope(results)
+      return results.to_h if results.all? { |e| e.is_a?(Array) && e.size == 2 }
+
+      results
+    end
+
+    def expect_rows!(slice, got)
+      expected = slice.sum { |_, _, text, _| Array(text).size }
+      return if got >= expected
+
+      raise ShortReplyError, "expected #{expected} VALUES rows, got #{got}"
+    end
+
+    def assign_rows(loader, slice, rows)
+      offset = 0
+      slice.each do |item|
+        _, _, text, = item
+        texts = Array(text)
+        values = rows[offset, texts.size]
+        offset += texts.size
+        loader.call(item, values.size == 1 ? values.first : values)
+      end
+    end
+
+    def resolve_entries(loader, slice, results)
+      expect_entries!(slice, results.size)
+      offset = 0
+      slice.each do |item|
+        _, _, text, = item
+        texts = Array(text)
+        values = entry_values(results, offset, texts)
+        offset += texts.size
+        loader.call(item, values.size == 1 ? values.first : values)
+      end
+    end
+
+    # A short multi-model reply is a protocol violation: an explicit null slot
+    # is the only legal way to signal a missing pair (see the BLOB path).
+    def expect_entries!(slice, got)
+      expected = slice.sum { |_, _, text, _| Array(text).size }
+      return if got >= expected
+
+      raise ShortReplyError, "expected #{expected} VALUES reply entries, got #{got}"
+    end
+
+    def entry_values(results, offset, texts)
+      results[offset, texts.size].map { |entry| entry && row_of(entry) }
+    end
+
+    def row_of(entry)
+      envelope = Emb::ValuesReply.parse(entry)
+      Emb::ValuesReply.rows(envelope[:shape], envelope[:values]).first
+    end
+  end
+end

data/lib/emb/values_reply.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Emb
+  # Decoding for EMB VALUES envelopes (the RedisAI META+VALUES shape). The
+  # server replies with flat alternating key/value pairs under RESP2 — dtype,
+  # shape, values — where values are decimal bulk strings carrying the float64
+  # widening of each float32 dimension.
+  module ValuesReply
+    module_function
+
+    # Parses one envelope into a Hash. RESP2 replies arrive as a flat 6-element
+    # pair array; under `protocol: 3` redis-client already decoded the server's
+    # RESP3 map into a Ruby Hash (keys frozen strings, values already Floats),
+    # which is used directly. values are converted to Ruby Floats; an
+    # unparsable entry raises ArgumentError naming the offending value.
+    def parse(reply)
+      pairs = reply.is_a?(Hash) ? reply : reply.each_slice(2).to_h
+      shape = pairs.fetch('shape')
+      values = Array(pairs.fetch('values')).map { |v| float_value(v) }
+      { dtype: pairs.fetch('dtype'), shape: shape, values: values }
+    end
+
+    # rows reshapes flat values into per-text rows using shape [m, dim].
+    def rows(shape, values)
+      dim = shape[1].to_i
+      values.each_slice(dim).to_a
+    end
+
+    def float_value(v)
+      Float(v)
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "EMB VALUES: unparsable decimal value #{v.inspect} (expected a numeric bulk string)"
+    end
+  end
+end

data/lib/emb.rb

@@ -36,14 +36,29 @@ module Emb
     def info(name)  = default_client.info(name)
     def stats       = default_client.stats
     def server_info(*sections)  = default_client.server_info(*sections)
+    def cache_flush(model = nil) = default_client.cache_flush(model)
+    def save_cache               = default_client.save_cache
     def config                  = default_client.config
     def help        = default_client.help
     def ping        = default_client.ping
     def ready       = default_client.ready
     def ready?      = default_client.ready?
     def multi(&)    = default_client.multi(&)
+
+    def eval(model, script, texts, args = [], decode: nil)
+      default_client.eval(model, script, texts, args, decode: decode)
+    end
+
+    def evalsha(model, sha, texts, args = [], decode: nil)
+      default_client.evalsha(model, sha, texts, args, decode: decode)
+    end
+
+    def script = default_client.script
+
     def reset_registry! = default_client.reset_registry!
+
     def debug? = @debug
+
     def send_command(*) = default_client.send_command(*)
 
     def debug!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: emb
 version: !ruby/object:Gem::Version
-  version: 0.4.0.pre1
+  version: 0.4.0.pre4
 platform: ruby
 authors:
 - elcuervo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: batch-loader
@@ -63,6 +63,9 @@ files:
 - lib/emb/railtie.rb
 - lib/emb/round_robin_pool.rb
 - lib/emb/runtime_config.rb
+- lib/emb/script_reply_decode.rb
+- lib/emb/values_batch.rb
+- lib/emb/values_reply.rb
 - lib/emb/version.rb
 homepage: https://github.com/elcuervo/emb
 licenses: