emb 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc1be692fe3d651429a292c2e2d0b912aa1bb8af22dbf56b9390d7e8a00fe516
-  data.tar.gz: 433caba4f427a465b9717970884ea64e12c4169fca3f54df8e91858dc1ef21bb
+  metadata.gz: da3d0c2517e4def78e7d887bd480cf3db14d2c83ba66eff0853ddf075fc1b785
+  data.tar.gz: 586bd53ce50bd1d1b427aaa82811676e193009155991dbe20f3496bf45816c7b
 SHA512:
-  metadata.gz: 553e753f5a90217312bd7f6e2e9240c16747b6fcc01e876cdabdc2b33a2c430cb937cb214926ee8a4d3fb77a66a45439ad6fb6c1be1885617fb0fa68026ee336
-  data.tar.gz: 478a17bbf82026da26580ead85fae29bd6f8b1350bbe841aa32b098ce0845e3005641a80f388fd7912df0ba3e2c9652a98d8dfda8769a8d48c3ceb1d3eed1ae4
+  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

@@ -20,16 +20,95 @@ 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
+```
+
+## 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 +118,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 +137,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 +164,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 +192,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,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
-    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?
+
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = @pool.with { |r| r.call(*args) }
+      elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
 
-    private
+      $stdout.puts "[EMB] #{args.map(&:inspect).join(' ')} (#{format('%.2f', elapsed)}ms)"
 
-    def pool
-      @pool ||= default_pool
+      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
 
@@ -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,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")
+    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 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.0
 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