emb 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc1be692fe3d651429a292c2e2d0b912aa1bb8af22dbf56b9390d7e8a00fe516
-  data.tar.gz: 433caba4f427a465b9717970884ea64e12c4169fca3f54df8e91858dc1ef21bb
+  metadata.gz: 424790b9a9b835dd7febbdfa1df2e5f8b6a2a9b89290b5e653467fcc09e4f68f
+  data.tar.gz: d21f28bb4c79deaefa9bab91247f41ff5e84f869b422727939ab1f07a940eb34
 SHA512:
-  metadata.gz: 553e753f5a90217312bd7f6e2e9240c16747b6fcc01e876cdabdc2b33a2c430cb937cb214926ee8a4d3fb77a66a45439ad6fb6c1be1885617fb0fa68026ee336
-  data.tar.gz: 478a17bbf82026da26580ead85fae29bd6f8b1350bbe841aa32b098ce0845e3005641a80f388fd7912df0ba3e2c9652a98d8dfda8769a8d48c3ceb1d3eed1ae4
+  metadata.gz: eacbde1ca9ccf217bd53cb9028f8a5192427754abcee678373d38f16b08ce4ae00b5b905909cb0d7ef0f07fa04b39c0ad112c820c6f4fd6d3c98ba06708af854
+  data.tar.gz: 8605fe8eaede9567d6506f5247ef85dfcb32b9c1c1fa719d00ce2446233b0518cbd336e6f496c8449ac41ab33545776b05d1febe2bf3d5a576aafa47afa60d9c

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

@@ -20,16 +20,118 @@ gem install emb
 
 ## Setup
 
-Configure the connection pool (defaults shown):
+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
+```
+
+### Redis client options
+
+Any `RedisClient` option can be forwarded through `Emb.setup` or `Emb.new`:
+
+```ruby
+Emb.setup(
+  url: "redis://localhost:6379",
+  pool: 10,
+  connect_timeout: 2,
+  read_timeout: 10,
+  write_timeout: 5,
+  reconnect_attempts: 5,
+  ssl: true,
+  ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER },
+  driver: :hiredis,
+  inherit_socket: true
+)
+```
+
+See the [redis-client documentation](https://github.com/redis-rb/redis-client) for
+all available options. Only `pool` is handled by the gem — everything else passes
+through to `RedisClient.new`.
+
+## 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
+```
+
+### Global convenience API
+
+When you don't need multiple clients, use the module-level methods:
+
+```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
@@ -39,6 +141,13 @@ 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
@@ -51,11 +160,21 @@ results = Emb[:minilm]["hello", "world"]
 Send texts to different models in one round trip:
 
 ```ruby
-Emb.multi do |m|
+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"
 ```
 
 ### Commands
@@ -68,7 +187,23 @@ Emb.help     # => command reference string
 Emb.ping     # => "PONG"
 ```
 
-## Testing end to end
+## Development
+
+### Console
+
+Start an IRB session with the gem loaded:
+
+```bash
+bundle exec rake console
+```
+
+### Lint
+
+```bash
+bundle exec rubocop
+```
+
+### Tests
 
 Start the emb server, then run the test suite:
 
@@ -80,4 +215,5 @@ Start the emb server, then run the test suite:
 bundle exec rake
 ```
 
-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,36 +1,99 @@
 # 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(pool: DEFAULTS[:pool], **redis_options)
+      url = extract_url!(redis_options)
+      redis_options[:host] ||= DEFAULTS[:host] unless url
+      redis_options[:port] ||= DEFAULTS[:port] unless url
+      redis_options[:protocol] ||= 2
+      redis_options[:reconnect_attempts] ||= 3
 
-  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)
+        RedisClient.new(url: url, **redis_options)
       end
-    end
 
-    alias_method :config, :setup
+      @registry = {}
+    end
 
     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
+
+      $stdout.puts "[EMB] #{args.map(&:inspect).join(' ')} (#{format('%.2f', elapsed)}ms)"
+
+      result
+    end
 
-    def pool
-      @pool ||= default_pool
+    def [](name)
+      @registry[name] ||= Proxy.new(self, name.to_sym)
     end
 
-    def default_pool
-      ConnectionPool.new(size: DEFAULTS[:pool]) do
-        RedisClient.new(host: DEFAULTS[:host], port: DEFAULTS[:port], protocol: 2, reconnect_attempts: 3)
+    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 ready
+      send_command('EMB.READY')
+
+      "ready"
+    rescue RedisClient::CommandError => e
+      e.message
+    end
+
+    def ready?
+      ready
+
+      true
+    rescue RedisClient::CommandError
+      false
+    end
+
+    def reset_registry!
+      @registry = {}
+    end
+
+    def multi(&)
+      mp = MultiProxy.new(self)
+      yield mp
+      mp.run
+    end
+
+    private
+
+    def extract_url!(opts)
+      url = opts.delete(:url)
+      url.nil? ? ENV.fetch('EMB_URL', nil) : url
+    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
 
@@ -13,7 +14,9 @@ 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
@@ -23,19 +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,28 +1,17 @@
 # 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)
-      set = Array(Emb.send_command("EMB", @name.to_s, text, *texts))
-      result = set.map { |entry| entry.unpack("e*") }
+      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
 

data/lib/emb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Emb
-  VERSION = Gem.loaded_specs['emb'].version.to_s
+  VERSION = Gem.loaded_specs['emb']&.version&.to_s || '0.0.0'
 end

data/lib/emb.rb

@@ -1,36 +1,41 @@
 # 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")
+    def new(...) = Client.new(...)
 
-      return [] if raw.nil?
-
-      raw.map do |name, dim, status|
-        { name: name, dim: dim.to_i, status: status }
-      end
+    def setup(...)
+      @default_client = Client.new(...)
     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] }
+    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 ready       = default_client.ready
+    def ready?      = default_client.ready?
+    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 stats = send_command("EMB.STATS")
+    private
 
-    def help = send_command("EMB.HELP")
-
-    def ping = send_command("PING")
+    def default_client
+      @default_client ||= Client.new
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: emb
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - elcuervo
@@ -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