epsilla-ruby 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 02ec2167e8966de5929e21521bcd3640683d4ac7a4c27b42c811a85714d4d7bc
+  data.tar.gz: 1c665e9af8e44e1a5f16b965c0996075ad4aa5833f6c92207c3492488293dc70
+SHA512:
+  metadata.gz: 72ad5416ad62fc593691288456294781a16aeb6aac85e12ef5257e133b2abd6df834963a3c2f40656d45235d7a5ea61b912716ba8b7250ad778192e403e09339
+  data.tar.gz: a805cb4f2ad872fbfeae05c7756bbb15f40d052cebc1c0fe68f4305e90078f0165095a104fec82de5759b5e43537bdf7544e65dd7f6ec899a4cc7ae8db4a05a5

data/README.md

@@ -0,0 +1,81 @@
+# Epsilla Ruby SDK
+
+Welcome to Ruby SDK for Epsilla Vector Database!
+
+## Installation
+```shell
+bundle add epsilla-ruby
+gem install epsilla-ruby
+```
+
+
+## Usage
+
+### Run Epsilla Vectordb using Docker
+```shell
+docker run --pull=always -d -p 8888:8888 epsilla/vectordb
+```
+
+### Use epsilla-ruby to connect to and interact with vector database
+```ruby
+
+require "epsilla"
+
+# Connect to Epsilla VectorDB
+client = Epsilla::Client.new(protocol="http", host="127.0.0.1", port="8888")
+# puts client.live?
+
+# Load DB with path
+status_code, response = client.database.load_db(db_name="MyDB", db_path="/tmp/epsilla")
+puts status_code, response
+
+# Set DB to current DB
+client.database.use_db(db_name="MyDB")
+
+# Create a table with schema in current DB
+table_fields= [
+  {"name" => "ID", "dataType" => "INT"},
+  {"name" => "Doc", "dataType" => "STRING"},
+  {"name" => "Embedding", "dataType" => "VECTOR_FLOAT", "dimensions" => 4}
+]
+# table_fields.each { |x| puts "==#{x}"}
+status_code, response = client.database.create_table(table_name="MyTable", table_fields=table_fields)
+puts status_code, response
+
+# Insert new vector records into table
+table_records = [
+  {"ID" => 1, "Doc" => "Berlin", "Embedding" => [0.05, 0.61, 0.76, 0.74]},
+  {"ID" => 2, "Doc" => "London", "Embedding" => [0.19, 0.81, 0.75, 0.11]},
+  {"ID" => 3, "Doc" => "Moscow", "Embedding" => [0.36, 0.55, 0.47, 0.94]},
+  {"ID" => 4, "Doc" => "San Francisco", "Embedding" => [0.18, 0.01, 0.85, 0.80]},
+  {"ID" => 5, "Doc" => "Shanghai", "Embedding" => [0.24, 0.18, 0.22, 0.44]}  
+]
+
+status_code, response = client.database.insert(table_name="MyTable", table_records=table_records)
+puts status_code, response
+
+# Rebuild
+status_code, response = client.database.rebuild()
+puts status_code, response
+
+# Query Vectors
+query_field = "Embedding"
+response_fields = ["Doc"]
+query_vector=[0.35, 0.55, 0.47, 0.94]
+limit=1
+status_code, response = client.database.query(table_name="MyTable", query_field=query_field, query_vector=query_vector, response_fields=response_fields, limit=limit, with_distance=true)
+puts status_code, response
+
+
+# Drop table
+status_code, response = client.database.drop_table("MyTable")
+puts status_code, response
+
+# Unload db
+status_code, response = client.database.unload_db("MyDB")
+puts status_code, response
+
+```
+
+## Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/epsilla-cloud/epsilla-ruby.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/examples/hello_epsilla.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+
+# Try this simple example
+# 1. docker run --pull=always -d -p 8888:8888 epsilla/vectordb
+# 2. gem install epsilla-ruby && gem update epsilla-ruby
+# 3. ruby hello_epsilla.rb
+
+
+require "epsilla"
+
+# Connect to Epsilla VectorDB
+client = Epsilla::Client.new(protocol="http", host="127.0.0.1", port="8888")
+# puts client.live?
+
+# Load DB with path
+status_code, response = client.database.load_db(db_name="MyDB", db_path="/tmp/epsilla")
+puts status_code, response
+
+# Set DB to current DB
+client.database.use_db(db_name="MyDB")
+
+# Create a table with schema in current DB
+table_fields= [
+  {"name" => "ID", "dataType" => "INT"},
+  {"name" => "Doc", "dataType" => "STRING"},
+  {"name" => "Embedding", "dataType" => "VECTOR_FLOAT", "dimensions" => 4}
+]
+# table_fields.each { |x| puts "==#{x}"}
+status_code, response = client.database.create_table(table_name="MyTable", table_fields=table_fields)
+puts status_code, response
+
+# Insert new vector records into table
+table_records = [
+  {"ID" => 1, "Doc" => "Berlin", "Embedding" => [0.05, 0.61, 0.76, 0.74]},
+  {"ID" => 2, "Doc" => "London", "Embedding" => [0.19, 0.81, 0.75, 0.11]},
+  {"ID" => 3, "Doc" => "Moscow", "Embedding" => [0.36, 0.55, 0.47, 0.94]},
+  {"ID" => 4, "Doc" => "San Francisco", "Embedding" => [0.18, 0.01, 0.85, 0.80]},
+  {"ID" => 5, "Doc" => "Shanghai", "Embedding" => [0.24, 0.18, 0.22, 0.44]}  
+]
+
+status_code, response = client.database.insert(table_name="MyTable", table_records=table_records)
+puts status_code, response
+
+# Rebuild
+status_code, response = client.database.rebuild()
+puts status_code, response
+
+# Query Vectors
+query_field = "Embedding"
+response_fields = ["Doc"]
+query_vector=[0.35, 0.55, 0.47, 0.94]
+limit=1
+status_code, response = client.database.query(table_name="MyTable", query_field=query_field, query_vector=query_vector, response_fields=response_fields, limit=limit, with_distance=true)
+puts status_code, response
+
+
+# Drop table
+status_code, response = client.database.drop_table("MyTable")
+puts status_code, response
+
+# Unload db
+status_code, response = client.database.unload_db("MyDB")
+puts status_code, response
+
+
+

data/lib/epsilla/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Epsilla
+  class Base
+    attr_reader :client
+
+    def initialize(client:)
+      @client = client
+    end
+  end
+end

data/lib/epsilla/client.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+
+module Epsilla
+  class Client
+    attr_reader :protocol, :host, :port, :adapter, :debug
+  
+    def self.welcome
+      puts "WELCOME To EPSILLA VECTOR DATABASE!"
+    end
+
+    def initialize(protocol, host, port, adapter: Faraday.default_adapter, debug: false)
+      @url = "#{protocol}://#{host}:#{port}"
+      @adapter = adapter
+      @debug = debug
+    end
+  
+  
+    def connection
+      @conn ||= Faraday.new(url: "#{@url}", request: { timeout: 30 }) do |faraday|
+        faraday.request :json
+        faraday.response :logger if @debug
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter @adapter
+        faraday.options.timeout = 30 # 30s
+        faraday.options.open_timeout = 30 # 30s
+        faraday.headers['Content-type'] = 'application/json'
+      end
+    end
+  
+    def live?
+      @health ||= Epsilla::Health.new(client: self)
+      @health.live?
+    end
+
+    def state
+      @health ||= Epsilla::Health.new(client: self)
+      @health.state
+    end
+
+    def database
+      @database ||= Epsilla::DataBase.new(client: self)
+    end
+    
+  end
+end

data/lib/epsilla/database.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Epsilla
+  class DataBase < Base
+
+    # use db
+    def use_db(db_name)
+      @db_name = db_name
+    end
+
+    # load db
+    def load_db(db_name, db_path, vector_scale: nil, wal_enabled: false)
+      response = client.connection.post do |req|
+        req.url "/api/load"
+        req.body = {"name": db_name, "path": db_path}.to_json
+        req.body["vectorScale"] = vector_scale if vector_scale
+        req.body["walEnabled"] = wal_enabled if wal_enabled
+      end
+      return response.status, response.body
+    end
+
+    # unload db
+    def unload_db(db_name)
+      @db_name = nil
+      response = client.connection.post do |req|
+        req.url "/api/#{db_name}/unload"
+      end
+      return response.status, response.body
+    end
+
+    # create table in the db
+    def create_table(table_name = "MyTable", table_fields = nil)
+      unless @db_name
+          raise Exception("[ERROR] Please use_db() first!")
+      end
+      unless table_fields
+          table_fields = Array.new
+      end
+
+      response = client.connection.post do |req|
+        req.url "/api/#{@db_name}/schema/tables"
+        req.body = {"name": table_name, "fields": table_fields}.to_json
+      end
+
+      return response.status, response.body
+    end
+
+    # insert data into table
+    def insert(table_name = "MyTable", table_records = nil)
+      unless @db_name
+        raise Exception("[ERROR] Please use_db() first!")
+      end
+      unless table_records
+        table_records = Array.new
+      end
+      response = client.connection.post do |req|
+        req.url "/api/#{@db_name}/data/insert"
+        req.body = {"table": table_name, "data": table_records}.to_json
+      end
+      
+      return response.status, response.body
+    end
+
+    # rebuild the table
+    def rebuild
+      # puts "[INFO] waiting until rebuild is finished ..."
+      response = client.connection.post do |req|
+        req.url '/api/rebuild'
+        req.options.timeout = 7200 # 7200s
+      end
+      return response.status, response.body
+    end
+
+    # query
+    def query(table_name = "MyTable", query_field = "", query_vector = nil, response_fields = nil, limit = 1, with_distance = false)
+      unless @db_name
+        raise Exception("[ERROR] Please use_db() first!")
+      end
+      unless query_vector
+        query_vector = ""
+      end
+      unless response_fields
+        response_fields = Array.new
+      end
+
+      response = client.connection.post do |req|
+        req.url "/api/#{@db_name}/data/query"
+        req.body = {"table": table_name, "queryField": query_field, "queryVector": query_vector, "response": response_fields, "limit": limit, "withDistance": with_distance}.to_json
+      end
+      return response.status, response.body
+    end
+
+    # get 
+    def get(table_name= "MyTable", response_fields = nil)
+      unless @db_name
+        raise Exception("[ERROR] Please use_db() first!")
+      end
+      unless response_fields
+        response_fields = Array.new
+      end
+      response = client.connection.post do |req|
+        req.url "/api/#{@db_name}/data/get"
+        req.body = {"table": table_name, "response": response_fields}.to_json
+      end
+      return response.status, response.body
+    end
+
+    # drop table
+    def drop_table(table_name)
+      unless @db_name
+        raise Exception("[ERROR] Please use_db() first!")
+      end     
+      response = client.connection.delete do |req|
+        req.url "/api/#{@db_name}/schema/tables/#{table_name}"
+      end
+      return response.status, response.body
+    end
+
+    # drop db
+    def drop_db(db_name)
+      response = client.connection.delete do |req|
+        req.url "/api/#{@db_name}/drop"
+      end
+      return response.status, response.body
+    end
+
+  end
+end

data/lib/epsilla/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Epsilla
+  class Error < StandardError
+  end
+end

data/lib/epsilla/health.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Epsilla
+  class Health < Base
+
+    def live?
+      response = client.connection.get do |req|
+        req.url '/'
+      end
+      if response.status != 200
+        raise Exception.new "[ERROR] Failed to connect to #{@url}"
+      else
+        true
+      end
+    end
+
+    def state
+      response = client.connection.get("/state")
+      response.status == 200
+    end
+  end
+end

data/lib/epsilla/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Epsilla
+  VERSION = "0.0.1"
+end

data/lib/epsilla.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "epsilla/version"
+
+module Epsilla
+  autoload :Base, "epsilla/base"
+  autoload :Client, "epsilla/client"
+  autoload :DataBase, "epsilla/database"
+  autoload :Health, "epsilla/health"
+  autoload :Error, "epsilla/error"
+end

data/sig/epsilla.rbs

@@ -0,0 +1,4 @@
+module Epsilla
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: epsilla-ruby
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Epsilla Team
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2023-08-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+description: EpsillaDB is a scalable, high-performance, and cost-effective vector
+  database
+email:
+- eric@epsilla.com
+- admin@epsilla.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- examples/hello_epsilla.rb
+- lib/epsilla.rb
+- lib/epsilla/base.rb
+- lib/epsilla/client.rb
+- lib/epsilla/database.rb
+- lib/epsilla/error.rb
+- lib/epsilla/health.rb
+- lib/epsilla/version.rb
+- sig/epsilla.rbs
+homepage: https://github.com/epsilla-cloud/vectordb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/epsilla-cloud/vectordb
+  source_code_uri: https://github.com/epsilla-cloud/epsilla-ruby
+  changelog_uri: https://github.com/epsilla-cloud/epsilla-ruby/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.18
+signing_key: 
+specification_version: 4
+summary: Ruby client for Epsilla Vector Database
+test_files: []