emb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4a415f04bd5c26d788aed81f94684054a563b26884c74d8ef7fa7f6eec909c7
-  data.tar.gz: 752cd3992f5cd48f31ec7f6d9387f04f36990532b7d9fbce88098c3a87e8eb9d
+  metadata.gz: da3d0c2517e4def78e7d887bd480cf3db14d2c83ba66eff0853ddf075fc1b785
+  data.tar.gz: 586bd53ce50bd1d1b427aaa82811676e193009155991dbe20f3496bf45816c7b
 SHA512:
-  metadata.gz: 7ccade7ad0c808e237a382f4a3172c35ca651b21082135c2a1d4202bdb03acd18c47ff1bcc1a06767a07cf4050d5d3b7fdfd5eaa0789c0bcfd78f24cd31784f1
-  data.tar.gz: d95c5f9c7064ecf7d61d1a81211909152ce8e465cf2c0e0f39d9d1585e7798210b68b6c4a76a450d641201ecafe834c5909d57c489204328a9404e4d014d8991
+  metadata.gz: 55aebcfa8f1ccdeca346309bd91d20e8527988593d1e76a4996d002e692ff2bfabf04119e65fa360c05ec04c3b8fa39f34166b72f1e3651eba071b97f024fc16
+  data.tar.gz: 2921b88b9cdb672f3ddcb54fba2ceb441772fc5791890487a30f17483abca57dd0a4e04f69534bdc0f33f5df1e20c0bb680394ef2a7822ddbe3164915914e82c

data/Gemfile

@@ -9,3 +9,7 @@ gem 'redis-client'
 
 gem 'rake', require: false
 gem 'rspec', require: false
+
+gem 'rubocop', require: false
+gem 'rubocop-rake', require: false
+gem 'rubocop-rspec', require: false

data/README.md

@@ -1,45 +1,196 @@
 # emb — Ruby client
 
-Thin Ruby wrapper for [emb](https://github.com/elcuervo/emb), a Redis-compatible embedding server.
+[![emb gem](https://img.shields.io/gem/v/emb?logo=rubygems&color=red&label=emb)](https://rubygems.org/gems/emb)
 
-## Usage
+Thin Ruby wrapper for [emb](https://github.com/elcuervo/emb), a Redis-compatible embedding server. Auto-decodes float32 binary responses to Ruby arrays.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "emb"
+```
+
+Or install globally:
+
+```bash
+gem install emb
+```
+
+## Setup
+
+The client connects to an emb server via the Redis protocol (RESP2). Configure with a URL,
+host/port, or rely on defaults and environment variables:
 
 ```ruby
 require "emb"
 
-Emb.setup(host: "localhost", port: 6379, pool: 5)
+# URL (Redis URL format)
+Emb.setup(url: "redis://localhost:6379")
+
+# Or individual params
+Emb.setup(host: "localhost", port: 6379)
+
+# Or rely on defaults
+Emb.setup
+```
+
+`Emb.config` is an alias for `Emb.setup`.
+
+### Configuration sources (priority order)
+
+1. Explicit `url:` or `host:`/`port:` arguments
+2. `EMB_URL` environment variable
+3. Default: `redis://localhost:6379`
+
+### Connection pool
+
+```ruby
+Emb.setup(url: "redis://localhost:6379", pool: 10)
+```
+
+### Authentication
+
+If the server is configured with a password, include it in the URL:
+
+```ruby
+# Password as URL userinfo
+Emb.setup(url: "redis://:hunter2@localhost:6379")
+```
+
+The `RedisClient` gem handles `AUTH` automatically on connect when a password
+is embedded in the URL. This works correctly with connection pooling — every
+connection in the pool authenticates on creation.
+
+Manual authentication is also possible but not recommended for pooled connections:
+
+```ruby
+Emb.send_command("AUTH", "hunter2")  # only authenticates one connection
+```
 
-Emb[:minilm]["hello world"]
-# → raw float32 bytes
+## Instance-based clients
+
+Create independent clients to connect to multiple servers or use different configurations:
+
+```ruby
+default = Emb.setup(url: "redis://localhost:6379")
+other   = Emb.new(url: "redis://:hunter2@10.0.0.1:6380")
+
+default.ping  # => "PONG"
+other.ping    # => "PONG"
+```
+
+Each client has its own connection pool and model proxy registry:
+
+```ruby
+c1 = Emb.new(url: "redis://server1:6379")
+c2 = Emb.new(url: "redis://server2:6379")
+
+c1[:minilm] != c2[:minilm]  # separate proxies
+```
 
-Emb.models
-# → [{name: "minilm", dim: 384, status: "ready"}, ...]
+### Global convenience API
 
-Emb.info(:minilm)
-# → {dim: 384, workers: 10, ...}
+When you don't need multiple clients, use the module-level methods:
 
-Emb.multi do |m|
+```ruby
+Emb.setup
+
+Emb[:minilm]["hello"]   # proxy access
+Emb.models               # list models
+Emb.info(:minilm)        # model info
+Emb.stats                # server stats
+Emb.help                 # command reference
+Emb.ping                 # health check
+```
+
+These all delegate to a lazily-initialized default client. No explicit `setup` call
+is required for simple cases — the default client connects to `redis://localhost:6379`
+automatically.
+
+## Usage
+
+### Single text
+
+```ruby
+result = Emb[:minilm]["hello world"]
+# => [0.0123, -0.0456, 0.0789, ...]  (384 floats)
+```
+
+With an instance-based client:
+
+```ruby
+client = Emb.new(url: "redis://localhost:6379")
+result = client[:minilm]["hello world"]
+```
+
+### Multiple texts
+
+```ruby
+results = Emb[:minilm]["hello", "world"]
+# => [[0.0123, ...], [-0.0456, ...]]
+```
+
+### Multi-model queries
+
+Send texts to different models in one round trip:
+
+```ruby
+results = Emb.multi do |m|
+  m[:minilm]["hello"]
+  m[:bge]["world"]
+end
+# => [[0.0123, ...], [-0.0456, ...]]
+# Results are unpacked from float32 binary — same format as single embeddings
+```
+
+Works the same on instance clients:
+
+```ruby
+client.multi do |m|
   m[:minilm]["hello"]
   m[:bge]["world"]
 end
-# → EMB.MULTI minilm "hello" bge "world"
 ```
 
-## Testing end to end
+### Commands
+
+```ruby
+Emb.models   # => [{name: "minilm", dim: 384, status: "ready"}, ...]
+Emb.info(:minilm)  # => {dim: 384, workers: 10, requests: 42, ...}
+Emb.stats    # => server statistics hash
+Emb.help     # => command reference string
+Emb.ping     # => "PONG"
+```
+
+## Development
+
+### Console
+
+Start an IRB session with the gem loaded:
+
+```bash
+bundle exec rake console
+```
+
+### Lint
 
-### Prerequisites
+```bash
+bundle exec rubocop
+```
 
-- An `emb` binary built from the repo root (`just build` or `go build`)
-- Ruby 3.3+ with bundler
+### Tests
 
-### Running tests
+Start the emb server, then run the test suite:
 
 ```bash
-# From the repo root, start the emb server:
+# From the repo root:
 ./bin/emb -config test-two-models.yaml &
 
-# From gems/emb/, run the test suite:
+# From gems/emb/:
 bundle exec rake
 ```
 
-This starts the full test suite against a real running `emb` server. Tests cover all commands: `EMB`, `EMB.MODELS`, `EMB.INFO`, `EMB.HELP`, `PING`, and `EMB.MULTI`.
+Tests cover all commands: `EMB`, `EMB.MODELS`, `EMB.INFO`, `EMB.HELP`, `PING`,
+and `EMB.MULTI`, plus instance-based clients, URL configuration, and connection pooling.

data/lib/emb/client.rb

@@ -1,35 +1,78 @@
 # frozen_string_literal: true
 
-require "connection_pool"
-require "redis_client"
+require 'connection_pool'
+require 'redis_client'
 
 module Emb
-  @pool = nil
+  DEFAULTS = { host: 'localhost', port: 6379, pool: 5 }.freeze
 
-  DEFAULTS = {host: "localhost", port: 6379, pool: 5}.freeze
+  class Client
+    attr_reader :pool
+
+    def initialize(url: nil, host: nil, port: nil, pool: DEFAULTS[:pool])
+      url ||= ENV['EMB_URL']
+      host ||= DEFAULTS[:host]
+      port ||= DEFAULTS[:port]
 
-  class << self
-    def setup(host: DEFAULTS[:host], port: DEFAULTS[:port], pool: DEFAULTS[:pool])
       @pool = ConnectionPool.new(size: pool) do
-        RedisClient.new(host: host, port: port, protocol: 2, reconnect_attempts: 3)
+        if url
+          RedisClient.new(url: url, protocol: 2, reconnect_attempts: 3)
+        else
+          RedisClient.new(host: host, port: port, protocol: 2, reconnect_attempts: 3)
+        end
       end
+
+      @registry = {}
     end
-    alias_method :config, :setup
 
     def send_command(*args)
-      pool.with { |r| r.call(*args) }
-    end
+      return @pool.with { |r| r.call(*args) } unless Emb.debug?
 
-    private
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = @pool.with { |r| r.call(*args) }
+      elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
 
-    def pool
-      @pool ||= default_pool
+      $stdout.puts "[EMB] #{args.map(&:inspect).join(' ')} (#{format('%.2f', elapsed)}ms)"
+
+      result
     end
 
-    def default_pool
-      ConnectionPool.new(size: DEFAULTS[:pool]) do
-        RedisClient.new(host: DEFAULTS[:host], port: DEFAULTS[:port], protocol: 2, reconnect_attempts: 3)
+    def [](name)
+      @registry[name] ||= Proxy.new(self, name.to_sym)
+    end
+
+    def models
+      raw = send_command('EMB.MODELS')
+      return [] if raw.nil?
+
+      raw.map do |name, dim, status|
+        { name: name, dim: dim.to_i, status: status }
       end
     end
+
+    def info(name)
+      raw = send_command('EMB.INFO', name.to_s)
+      return {} if raw.nil?
+
+      raw
+        .each_slice(2)
+        .to_h { |k, v| [k.to_sym, v] }
+    end
+
+    def stats = send_command('EMB.STATS')
+
+    def help = send_command('EMB.HELP')
+
+    def ping = send_command('PING')
+
+    def reset_registry!
+      @registry = {}
+    end
+
+    def multi(&)
+      mp = MultiProxy.new(self)
+      yield mp
+      mp.run
+    end
   end
 end

data/lib/emb/multi.rb

@@ -2,7 +2,8 @@
 
 module Emb
   class MultiProxy
-    def initialize
+    def initialize(client)
+      @client = client
       @pairs = []
     end
 
@@ -12,7 +13,10 @@ module Emb
 
     def run
       args = @pairs.flat_map { |pair| [pair[:model].to_s, pair[:text]] }
-      Emb.send_command("EMB.MULTI", *args)
+
+      @client
+        .send_command('EMB.MULTI', *args)
+        .map { |entry| entry.unpack('e*') }
     end
 
     class PairCollector
@@ -22,16 +26,8 @@ module Emb
       end
 
       def [](text)
-        @pairs << {model: @model, text: text}
+        @pairs << { model: @model, text: text }
       end
     end
   end
-
-  class << self
-    def multi
-      mp = MultiProxy.new
-      yield mp
-      mp.run
-    end
-  end
 end

data/lib/emb/proxy.rb

@@ -1,27 +1,21 @@
 # frozen_string_literal: true
 
 module Emb
-  @registry = {}
-
-  class << self
-    def [](name)
-      @registry[name] ||= Proxy.new(name.to_sym)
-    end
-
-    def reset_registry!
-      @registry.clear
-    end
-  end
-
   class Proxy
     attr_reader :name
 
-    def initialize(name)
+    def initialize(client, name)
+      @client = client
       @name = name
     end
 
     def [](text, *texts)
-      Emb.send_command("EMB", @name.to_s, text, *texts)
+      set = Array(@client.send_command('EMB', @name.to_s, text, *texts))
+      result = set.map { |entry| entry.unpack('e*') }
+
+      return result.first if result.size == 1
+
+      result
     end
 
     def inspect

data/lib/emb/version.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
 module Emb
-  VERSION =
-    begin
-      File.read(File.expand_path('../../../../VERSION', __dir__)).strip
-    rescue Errno::ENOENT
-      Gem::Specification.find_by_name("emb").version.to_s
-    end
+  VERSION = Gem.loaded_specs['emb']&.version&.to_s || '0.0.0'
 end

data/lib/emb.rb

@@ -1,30 +1,39 @@
 # frozen_string_literal: true
 
-require_relative "emb/version"
-require_relative "emb/client"
-require_relative "emb/proxy"
-require_relative "emb/multi"
+require_relative 'emb/version'
+require_relative 'emb/client'
+require_relative 'emb/proxy'
+require_relative 'emb/multi'
 
 module Emb
   class << self
-    def models
-      raw = send_command("EMB.MODELS")
-      return [] if raw.nil?
-      raw.map { |name, dim, status| {name: name, dim: dim.to_i, status: status} }
-    end
-
-    def info(name)
-      raw = send_command("EMB.INFO", name.to_s)
-
-      return {} if raw.nil?
+    def new(...) = Client.new(...)
 
-      raw.each_slice(2).map { |k, v| [k.to_sym, v] }.to_h
+    def setup(...)
+      @default_client = Client.new(...)
     end
 
-    def stats = send_command("EMB.STATS")
+    alias config setup
+
+    def [](name)    = default_client[name]
+    def models      = default_client.models
+    def info(name)  = default_client.info(name)
+    def stats       = default_client.stats
+    def help        = default_client.help
+    def ping        = default_client.ping
+    def multi(&)    = default_client.multi(&)
+    def reset_registry! = default_client.reset_registry!
+    def debug? = @debug
+    def send_command(*) = default_client.send_command(*)
+
+    def debug!
+      @debug = true
+    end
 
-    def help = send_command("EMB.HELP")
+    private
 
-    def ping = send_command("PING")
+    def default_client
+      @default_client ||= Client.new
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: emb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - elcuervo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: connection_pool
@@ -38,20 +38,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.24'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.13'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.13'
 description:
 email:
 - elcuervo@elcuervo.net