chroma-db 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8334143128edb78d734a0154da3432e1d8e222922341b182e1d589f91a227a3
-  data.tar.gz: 30f9c52759742ca2848e87df649c683a683bce9a00041abb9ed91a77b746dd9a
+  metadata.gz: 9273343cf2f29991d61d8e5393dfd06541211c84e03769162fa984c9ca2c8620
+  data.tar.gz: 3dd3e94d5914e5776aef673f18b06bbb6f61254bbe4eb51ae25f8675f6c9c72b
 SHA512:
-  metadata.gz: 41838e89fe84ef6317092a8fc604ae13ec99a2619fbb56fb18b72d2b5b837dd2fa550ebdb0e9802b6026ba487e250d5839d0417e59bcb99589137debdbec82ef
-  data.tar.gz: 2dfd54367af2f122265a51e1e9d2e228e58b14984f4aab91e940f732f682db7ea5744fb758bb114875165b5ca907be6493d6aa3d1b68637ff79d65c07b7f62b4
+  metadata.gz: 8c94d838879f22cae956b9a4b7e66f8b8a8d76792770dda6eb9a91b197aa0eb3b8408256653402feb750732f35fb221ae2ebedfe05ab49d89896b80579228ed0
+  data.tar.gz: f5ad7421b54da9909a3a1c76d36d07738ccd44aaa934a7e960e5b102608e24c61e36243b59c0d2ba469e01c34b2cc360e2a07a82516d1a4a2d73cfffa49334fa

data/Gemfile

@@ -12,3 +12,5 @@ gem "minitest", "~> 5.0"
 gem "standard", "~> 1.3"
 
 gem "rbs", "~> 3.1"
+
+gem "webmock", "~> 3.18", ">= 3.18.1"

data/Gemfile.lock

@@ -1,14 +1,18 @@
 PATH
   remote: .
   specs:
-    chroma-db (0.1.0)
+    chroma-db (0.2.0)
       dry-monads (~> 1.6)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.8.4)
+      public_suffix (>= 2.0.2, < 6.0)
     ast (2.4.2)
     concurrent-ruby (1.2.2)
+    crack (0.4.5)
+      rexml
     dry-core (1.0.0)
       concurrent-ruby (~> 1.0)
       zeitwerk (~> 2.6)
@@ -16,6 +20,7 @@ GEM
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.0, < 2)
       zeitwerk (~> 2.6)
+    hashdiff (1.0.1)
     json (2.6.3)
     language_server-protocol (3.17.0.3)
     lint_roller (1.0.0)
@@ -23,6 +28,7 @@ GEM
     parallel (1.23.0)
     parser (3.2.2.1)
       ast (~> 2.4.1)
+    public_suffix (5.0.1)
     rainbow (3.1.1)
     rake (13.0.6)
     rbs (3.1.0)
@@ -56,10 +62,15 @@ GEM
       lint_roller (~> 1.0)
       rubocop-performance (~> 1.16.0)
     unicode-display_width (2.4.2)
+    webmock (3.18.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
     zeitwerk (2.6.8)
 
 PLATFORMS
   arm64-darwin-22
+  x86_64-linux
 
 DEPENDENCIES
   chroma-db!
@@ -67,6 +78,7 @@ DEPENDENCIES
   rake (~> 13.0)
   rbs (~> 3.1)
   standard (~> 1.3)
+  webmock (~> 3.18, >= 3.18.1)
 
 BUNDLED WITH
    2.4.12

data/lib/chroma/api_operations/request.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Chroma
+  module APIOperations
+    # Request's response Data object.
+    #
+    # status - HTTP status code. It is zero when a request fails due to network error.
+    # body - Parsed JSON object or response body.
+    # headers - HTTP response headers.
+    # error - Exception or Net::HTTPResponse object if the response is not Net::HTTPSuccess
+    Response = Data.define(:status, :body, :headers, :error)
+
+    # Request module provides functionality to perform HTTP requests.
+    module Request
+      module ClassMethods
+        include Dry::Monads[:result]
+
+        # Execute an HTTP request and return a monad wrapping the response.
+        #
+        # method - The HTTP method to use (e.g. 'GET', 'POST'). Method must be a `Symbol`.
+        # url - The URL to send the request to.
+        # params - The query parameters or request body. Params needs to be in a form of a Hash.
+        # options - Additional options to pass to the request.
+        #
+        # A `Dry::Monads::Result` monad wrapping the response, either a success or failure.
+        # The response is a `Chroma::APIOperations::Response` Data object.
+        #
+        # Examples
+        #
+        #   result = execute_request(:get, "https://example.com", {name: "test request"})
+        #   if result.success?
+        #     puts "Response status: #{result.success.status}"
+        #     puts "Response body: #{result.success.body}"
+        #   else
+        #     puts "Request failed with error: #{result.failure.error}"
+        #   end
+        def execute_request(method, url, params = {}, options = {})
+          uri = URI.parse(url)
+
+          request = build_request(method, uri, params)
+
+          use_ssl = options.delete(:use_ssl) || false
+          response = Net::HTTP.start(uri.hostname, uri.port, use_ssl:) do |http|
+            Chroma::Util.log_debug("Sending a request", {method:, uri:, params:})
+            http.request(request)
+          end
+
+          build_response(response)
+        rescue => ex
+          build_response(ex)
+        end
+
+        private def build_response(response)
+          case response
+          in Net::HTTPSuccess => success_response
+            Chroma::Util.log_info("Successful response", code: success_response.code)
+
+            build_response_details(success_response)
+          in Net::HTTPRedirection => redirect_response
+            Chroma::Util.log_info("Server redirect response", code: redirect_response.code, location: redirect_response["location"])
+
+            build_response_details(redirect_response)
+          in Net::HTTPClientError => client_error_response
+            Chroma::Util.log_error("Client error response", code: client_error_response.code, body: client_error_response.body)
+
+            build_response_details(client_error_response)
+          in Net::HTTPServerError => server_error_response
+            Chroma::Util.log_error("Server error response", code: server_error_response.code)
+
+            build_response_details(server_error_response, parse_body: false)
+          else
+            Chroma::Util.log_error("An error happened", error: response.to_s)
+
+            build_response_details(response, exception: true, parse_body: false)
+          end
+        end
+
+        private def build_response_details(response, exception: false, parse_body: true)
+          response_data = Chroma::APIOperations::Response.new(
+            status: exception ? 0 : response.code.to_i,
+            body: if exception
+                    exception.to_s
+                  else
+                    (parse_body ? body_to_json(response.body) : response.body)
+                  end,
+            headers: exception ? {} : response.each_header.to_h,
+            error: response.is_a?(Net::HTTPSuccess) ? nil : response
+          )
+
+          case response
+          in Net::HTTPSuccess
+            return Success(response_data)
+          else
+            return Failure(response_data)
+          end
+        end
+
+        private def body_to_json(content)
+          JSON.parse(content, symbolize_keys: true)
+        rescue JSON::ParserError, TypeError
+          content
+        end
+
+        private def build_request(method, uri, params)
+          request = case method
+          when :post then Net::HTTP::Post.new(uri)
+          when :put then Net::HTTP::Put.new(uri)
+          when :delete then Net::HTTP::Delete.new(uri)
+          else
+            Net::HTTP::Get.new(uri)
+          end
+
+          request.content_type = "application/json"
+          request.body = params.to_json if params.size > 0
+
+          request
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/chroma/chroma.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Chroma
+  # map to the same values as the standard library's logger
+  LEVEL_DEBUG = Logger::DEBUG
+  LEVEL_ERROR = Logger::ERROR
+  LEVEL_INFO = Logger::INFO
+
+  @config = Chroma::ChromaConfiguration.setup
+
+  class << self
+    extend Forwardable
+
+    attr_reader :config
+
+    # User configuration options
+    def_delegators :@config, :connect_host, :connect_host=
+    def_delegators :@config, :api_base, :api_base=
+    def_delegators :@config, :api_version, :api_version=
+    def_delegators :@config, :log_level, :log_level=
+    def_delegators :@config, :logger, :logger=
+  end
+
+  def self.api_url
+    "#{connect_host}/#{api_base}/#{api_version}"
+  end
+
+  Chroma.log_level = ENV["CHROMA_LOG"].to_i unless ENV["CHROMA_LOG"].nil?
+end

data/lib/chroma/chroma_configuration.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Chroma
+  # The ChromaConfiguration class allows you to configure the connection settings for a Chroma service client.
+  # It can be initialized directly calling #new method.
+  #
+  # Examples
+  #
+  #   configuration = Chroma::ChromaConfiguration.new
+  #   configurarion.connect_host = "https://chroma.example.com"
+  #
+  # Or via a setup block.
+  #
+  # Examples
+  #
+  #   Chroma::ChromaConfiguration.setup do |config|
+  #     config.connect_host = "https://chroma.example.com"
+  #   end
+  class ChromaConfiguration
+    # Sets the host name for the Chroma service.
+    #
+    # Examples
+    #
+    #   config.connect_host = "chroma.example.com"
+    #
+    # Returns the String host name.
+    attr_accessor :connect_host
+
+    # Sets the base path for the Chroma API.
+    #
+    # Examples
+    #
+    #   config.api_base = "/api"
+    #
+    # Returns the String API base path.
+    attr_accessor :api_base
+    # Sets the version of the Chroma API.
+    #
+    # Examples
+    #
+    #   config.api_version = "v1"
+    #
+    # Returns the String API version.
+    attr_accessor :api_version
+    # Sets the logger for the Chroma service client.
+    #
+    # Examples
+    #
+    #   config.logger = Logger.new(STDOUT)
+    #
+    # Returns the Logger instance.
+    attr_accessor :logger
+    # Sets the logger's log level for the Chroma service client.
+    #
+    # Examples
+    #
+    #   config.log_level = Chroma::LEVEL_INFO
+    #
+    # Returns the log level constant
+    attr_accessor :log_level
+
+    def self.setup
+      new.tap do |instance|
+        yield(instance) if block_given?
+      end
+    end
+
+    def initialize
+      @api_base = "api"
+      @api_version = "v1"
+
+      @log_level = Chroma::LEVEL_INFO
+    end
+  end
+end

data/lib/chroma/errors.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Chroma
+  # ChromaError is the base error from which all other more specific Chrome
+  # errors derive.
+  class ChromaError < StandardError
+    attr_accessor :response
+
+    attr_reader :message
+    attr_reader :error
+    attr_reader :body
+    attr_reader :status
+
+    def initialize(message = nil, status: nil, body: nil, response: nil)
+      @message = message
+      @status = status
+      @body = body
+      @response = response
+    end
+
+    def to_s
+      status_value = @status.nil? ? "" : "(Status #{@status}) "
+      "#{status_value}#{@message}"
+    end
+  end
+
+  # APIConnectionError is raised in the event that the SDK can't connect to
+  # Chroma's database. That can be for a variety of different reasons from a
+  # downed network to a bad TLS certificate.
+  class APIConnectionError < ChromaError
+  end
+
+  # InvalidRequestError is raised when a request is initiated with invalid
+  # parameters.
+  class InvalidRequestError < ChromaError
+    def initialize(message = nil, status: nil, body: nil, response: nil)
+      super
+
+      decode_message
+    end
+
+    private
+
+    def decode_message
+      if message.include?("ValueError")
+        error = JSON.parse(message)
+        value = error.fetch("error", "").sub("ValueError('", "").sub("')", "")
+        @message = value if !value.nil?
+      end
+    rescue JSON::ParserError, TypeError
+    end
+  end
+
+  # APIError is a generic error that may be raised in cases where none of the
+  # other named errors cover the problem.
+  class APIError < ChromaError
+    def initialize(message = nil, status: nil, body: nil, response: nil)
+      super
+
+      decode_message
+    end
+
+    private
+
+    def decode_message
+      if message.is_a?(Hash) && message.has_key?("error")
+        @message = message.fetch("error")
+      end
+    end
+  end
+end