weaviate_record 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: af84dff0fba26b232fd8b537749ff5742f5bcc0197656cc647e8b6791a55bd85
+  data.tar.gz: 9534adbc21943b257d0e8f0a517721dd17bb93a1d1e3c14f284e11f30499f1f9
+SHA512:
+  metadata.gz: e7d0fda549172607928d6e943426f5091d481d4cbcd4c44bb767a32ef667769091238125f79926c1070358dc1095a191e52af70d20ea915b17acbf4eeac51beb
+  data.tar.gz: dde3def3b42f332182c8d7f8cc115a1516f177be5abedbd516713e00474f9c1b7b9935da51ef134d9010b773df8acb95d2f867a4be043765edef53308e97b201

data/lib/weaviate_record/base.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module WeaviateRecord
+  # Base class for the models to inherit from and to interact with the respective collection in weaviate.
+  class Base
+    extend ActiveModel::Naming
+    include ActiveModel::Conversion
+    include ActiveModel::Validations
+    include Inspect
+    include MethodMissing
+    include Concerns::RecordConcern
+
+    class << self
+      extend Forwardable
+      def_delegators(:relation, :all, :bm25, :limit, :near_text, :near_vector, :near_object,
+                     :offset, :order, :select, :where, :ask, :destroy_all, :first, :last)
+
+      # Creates a new weaviate record and saves it and returns the record.
+      # Takes a key value pair of attributes that the record should be initialized with.
+      # If the record is not saved, it returns the unsaved record object with errors.
+      #
+      # ==== Example:
+      #  Article.create(title: 'Hello World', content: 'This is the content of the article')
+      #
+      #  # => #<Article:0x0000000105468ab0 id: "8280210b-9372-4e70-a045-beb7c12a9a24" ...>
+      def create(**attributes_hash)
+        record = new(**attributes_hash)
+        record.save
+        record
+      end
+
+      # Takes an _uuid_ and returns the record with that _uuid_.
+      # If the record is not found, it raises a +RecordNotFoundError+.
+      #
+      # ==== Example:
+      #   Article.find('f3b1b3b1-0b3b-4b3b-8b3b-0b3b3b3b3b3b')
+      #
+      #   #<Article:0x0000000105468ab0 id: "8280210b-9372-4e70-a045-beb7c12a9a24" ...>
+      def find(id)
+        result = connection.find_call(id)
+        if result.is_a?(Hash) && result['id']
+          new(_additional: meta_attributes(result), **result['properties'])
+        elsif result == ''
+          raise WeaviateRecord::Errors::RecordNotFoundError, "Couldn't find record with id=#{id}"
+        else
+          raise WeaviateRecord::Errors::ServerError, result['message']
+        end
+      end
+
+      # Returns the count of all records in the collection.
+      #
+      # ==== Example:
+      #    class Article < WeaviateRecord::Base
+      #    end
+      #
+      #    Article.count # => 0
+      #
+      #    Article.create(title: 'Hello World', content: 'This is the content of the article')
+      #
+      #    Article.count # => 1
+      def count
+        result = connection.client.query.aggs(class_name: to_s, fields: 'meta { count }')
+        result.dig(0, 'meta', 'count')
+      rescue StandardError
+        raise WeaviateRecord::Errors::ServerError, "unable to get the count for #{self} collection."
+      end
+
+      # Takes an _uuid_ and checks whether a record with that id exists or not.
+      #
+      # ==== Example:
+      #   Article.exists?('f3b1b3b1-0b3b-4b3b-8b3b-0b3b3b3b3b3b')  # => true
+      #   Article.exists?('random_uuid')  # => false
+      def exists?(id)
+        connection.check_existence(id)
+      end
+
+      private
+
+      def connection
+        @connection ||= Connection.new(self)
+      end
+
+      def relation
+        WeaviateRecord::Relation.new(self)
+      end
+
+      def inherited(klass)
+        WeaviateRecord::Schema.find_collection(klass)
+        super
+      end
+    end
+
+    # Creates a new record with the given attributes.
+    # The attributes can be passed as a hash or as key value pairs.
+    # It does not save the record in the weaviate database.
+    #
+    #
+    # ==== Example:
+    #  Article.new(title: 'Hello World', content: 'This is the content of the article')
+    #
+    #  # => #<Article:0x0000000105468ab0 ... "Hello World", content: "This is the content of the article">
+    #
+    #  Article.title # => "Hello World"
+    #  Article.content # => "This is the content of the article"
+    #
+    #  Article.title = 'Not Hello World'
+    #  Article.title # => "Not Hello World"
+    #
+    #  Article.persisted? # => false
+    #
+    #
+    # The +custom_selected+ parameter is used to indicate whether the attributes are custom picked.
+    # If the attributes are custom picked, the attribute readers will be defined only for the selected attributes.
+    # The record with custom_selected as true cannot be saved, updated, or destroyed.
+    def initialize(hash = {}, custom_selected: false, **attributes)
+      attributes_hash = (hash.present? ? hash : attributes).deep_transform_keys(&:to_s)
+      @connection = WeaviateRecord::Connection.new(collection_name)
+      @custom_selected = custom_selected
+      @attributes = {}
+      @meta_attributes = attributes_hash['_additional'] || { 'id' => nil, 'creationTimeUnix' => nil,
+                                                             'lastUpdateTimeUnix' => nil }
+      run_attribute_handlers(attributes_hash)
+    end
+
+    # Saves the record in the weaviate database.
+    # Returns true if the record is saved successfully. Otherwise, it returns false.
+    # If the record is not saved successfully, it adds the errors to the record.
+    # If the record is already saved, it updates the record.
+    #
+    # ==== Example:
+    #  class Article < WeaviateRecord::Base
+    #    validates :title, presence: true
+    #  end
+    #
+    #  article = Article.new(title: 'Hello World', content: 'This is the content of the article')
+    #  article.save # => true
+    #
+    #  article.title = 'New title'
+    #  article.save # => true
+    #
+    #  article.title # => "New title"
+    #
+    #  article = Article.new(title: '')
+    #  article.save # => false
+    #  article.errors.full_messages # => ["Title can't be blank"]
+    #
+    def save
+      result = validate_and_save
+      return false unless result
+
+      if result['error'].present?
+        errors.add(:base, message: result['error'])
+        false
+      else
+        @meta_attributes.merge!(self.class.meta_attributes(result))
+        true
+      end
+    end
+
+    # Updates the record in the weaviate database.
+    # Returns true if the record is updated successfully. Otherwise, it returns false.
+    # If the record is not updated successfully, it adds the errors to the record.
+    #
+    # ==== Example:
+    #  class Article < WeaviateRecord::Base
+    #   validates :title, presence: true
+    #  end
+    #
+    #  article = Article.new(title: 'Hello World', content: 'This is the content of the article')
+    #  article.save
+    #
+    #  article.update(title: 'Not Hello World') # => true
+    #  article.title # => "Not Hello World"
+    #
+    #  article.update(title: '') # => false
+    #  article.errors.full_messages # => ["Title can't be blank"]
+    #
+    # If you try to update the meta attribute, it will raise an error
+    #
+    # ==== Example:
+    #  article.update(id: 'new_id')
+    #  # => WeaviateRecord::Errors::MetaAttributeError: 'cannot update meta attributes'
+    def update(hash = {}, **attributes)
+      attributes_hash = (hash.present? ? hash : attributes).deep_transform_keys(&:to_s)
+      validate_record_for_update(attributes_hash)
+      merge_attributes(attributes_hash)
+      return false unless valid?
+
+      result = @connection.update_call(@meta_attributes['id'], @attributes)
+      raise WeaviateRecord::Errors::ServerError, 'unable to update the weaviate record' unless result.is_a?(Hash)
+
+      errors.add(:base, message: result['error']) if result['error'].present?
+      result['id'].present?
+    end
+
+    # Destroys the record in the weaviate database.
+    # Returns true if the record is destroyed successfully. Otherwise, it returns false.
+    # If the record is the original record with valid id, it freezes the existing record object.
+    # If the record does not have a valid id, it converts all the attributes to nil.
+    #
+    # ==== Example:
+    #  article = Article.new(title: 'Hello World', content: 'This is the content of the article')
+    #
+    #  article.destroy # => false
+    #  article.title   # => nil
+    #
+    #  article.title = 'New title'
+    #  article.save
+    #
+    #  article.destroy # => true
+    #
+    #  article.frozen? # => true
+    def destroy
+      return self unless validate_record_for_destroy
+
+      result = @connection.delete_call(@meta_attributes['id'])
+      return freeze if result == true
+
+      errors.add(:base, message: result['error']) if result['error'].present?
+      false
+    end
+
+    # Checks whether the record is saved in the weaviate database or not.
+    # If the record is saved, it returns true. Otherwise, it returns false.
+    #
+    # ==== Example:
+    #  article = Article.new(title: 'Hello World', content: 'This is the content of the article')
+    #  article.save
+    #  article.persisted? # => true
+    def persisted?
+      if @custom_selected || !respond_to?(:id)
+        raise WeaviateRecord::Errors::CustomQueriedRecordError,
+              'cannot perform persisted? action on custom queried record'
+      end
+
+      id.present?
+    end
+  end
+end

data/lib/weaviate_record/concerns/attribute_concern.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module WeaviateRecord # :nodoc: all
+  module Concerns
+    module AttributeConcern
+      private
+
+      def list_of_valid_attributes
+        @list_of_valid_attributes ||= WeaviateRecord::Schema.find_collection(collection_name)
+                                                            .attributes_list
+      end
+
+      def check_attributes(attributes_hash)
+        invalid_attributes = attributes_hash.keys - ['_additional', *list_of_valid_attributes]
+        return unless invalid_attributes.present?
+
+        raise WeaviateRecord::Errors::InvalidAttributeError,
+              "Invalid attributes #{invalid_attributes} for #{collection_name} record!"
+      end
+
+      def merge_attributes(attributes_hash)
+        check_attributes(attributes_hash)
+        attributes_hash.each do |key, value|
+          @attributes[key] = value
+        end
+      end
+
+      def load_attributes(attributes_hash)
+        if attributes_hash.empty? || !@custom_selected
+          list_of_valid_attributes.each do |attribute|
+            @attributes[attribute] = nil
+          end
+        end
+
+        attributes_hash.each do |key, value|
+          next if key == '_additional'
+
+          @attributes[key] = value
+        end
+      end
+
+      def create_attribute_writers
+        list_of_valid_attributes.each do |name|
+          define_singleton_method("#{name}=") do |value|
+            @attributes[name] = value
+          end
+        end
+      end
+
+      def create_attribute_readers
+        attributes_list = @custom_selected ? @attributes.each_key : list_of_valid_attributes
+        attributes_list.each do |name|
+          define_singleton_method(name) { @attributes[name] }
+        end
+
+        handle_timestamp_attributes
+        @meta_attributes.each_key do |name|
+          define_singleton_method(name.underscore) { @meta_attributes[name] }
+        end
+      end
+
+      def handle_timestamp_attributes
+        replace_timestamp_attribute('creationTimeUnix') if @meta_attributes.key? 'creationTimeUnix'
+        replace_timestamp_attribute('lastUpdateTimeUnix') if @meta_attributes.key? 'lastUpdateTimeUnix'
+      end
+
+      def replace_timestamp_attribute(attribute)
+        mapped_attribute = WeaviateRecord::Constants::SPECIAL_ATTRIBUTE_MAPPINGS.key(attribute)
+        @meta_attributes[mapped_attribute] = if @meta_attributes[attribute]
+                                               DateTime.strptime(@meta_attributes[attribute], '%Q')
+                                             end
+        @meta_attributes.delete(attribute)
+      end
+    end
+  end
+end

data/lib/weaviate_record/concerns/record_concern.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module WeaviateRecord # :nodoc: all
+  module Concerns
+    module RecordConcern
+      extend ActiveSupport::Concern
+      include AttributeConcern
+
+      def collection_name
+        self.class.to_s
+      end
+
+      private
+
+      def run_attribute_handlers(attributes_hash)
+        check_attributes(attributes_hash)
+        load_attributes(attributes_hash)
+        create_attribute_writers
+        create_attribute_readers
+      end
+
+      def validate_record_for_update(attributes_hash)
+        raise ArgumentError, 'update action requires minimum one attribute' if attributes_hash.empty?
+        raise WeaviateRecord::Errors::MissingIdError, 'the record doesn\'t have an id' unless @meta_attributes['id']
+
+        if @custom_selected
+          raise WeaviateRecord::Errors::CustomQueriedRecordError,
+                'cannot perform update action on custom selected record'
+        end
+
+        check_attributes(attributes_hash)
+        return unless attributes_hash['_additional'] || attributes_hash[:_additional]
+
+        raise WeaviateRecord::Errors::MetaAttributeError, 'cannot update meta attributes'
+      end
+
+      def validate_and_save
+        if @custom_selected
+          raise WeaviateRecord::Errors::CustomQueriedRecordError, 'cannot modify custom selected record'
+        end
+        return false unless valid?
+
+        result = create_or_update_record
+        raise WeaviateRecord::Errors::InternalError, 'unable to save the record on Weaviate' unless result.is_a?(Hash)
+
+        result
+      end
+
+      def create_or_update_record
+        if @meta_attributes['id']
+          @connection.update_call(@meta_attributes['id'], @attributes)
+        else
+          @connection.create_call(@attributes)
+        end
+      end
+
+      def validate_record_for_destroy
+        if @custom_selected
+          raise WeaviateRecord::Errors::CustomQueriedRecordError,
+                'cannot perform destroy action on custom selected record'
+        end
+
+        return true if @meta_attributes['id']
+
+        @attributes.each_key { |key| @attributes[key] = nil }
+        false
+      end
+
+      class_methods do
+        def meta_attributes(record)
+          meta = {}
+          meta['id'] = record['id']
+          meta['created_at'] = DateTime.strptime(record['creationTimeUnix'].to_s, '%Q')
+          meta['updated_at'] = DateTime.strptime(record['lastUpdateTimeUnix'].to_s, '%Q')
+          meta
+        end
+      end
+    end
+  end
+end

data/lib/weaviate_record/connection.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'weaviate'
+
+module WeaviateRecord
+  # This module will act as a connection to Weaviate database
+  class Connection
+    # Returns a _Weaviate::Client_ object, which is used to interact with the Weaviate database.
+    attr_reader :client
+
+    # Creates a new Connection to the Weaviate database.
+    def initialize(collection_name = nil)
+      @collection_name = collection_name&.to_s
+      @client = Weaviate::Client.new(
+        url: ENV.fetch('WEAVIATE_DATABASE_URL'),
+        api_key: ENV.fetch('WEAVIATE_API_KEY', nil),
+        model_service: ENV['WEAVIATE_VECTORIZER_MODULE']&.to_sym,
+        model_service_api_key: ENV.fetch('WEAVIATE_VECTORIZER_API_KEY', nil)
+      )
+    end
+
+    # Returns the present schema of the Weaviate database.
+    def schema_list
+      client.schema.list.deep_symbolize_keys!
+    end
+
+    # :enddoc:
+
+    def find_call(id)
+      client.objects.get(class_name: @collection_name, id: id)
+    end
+
+    def create_call(properties)
+      client.objects.create(class_name: @collection_name, properties: properties)
+    end
+
+    def update_call(id, properties)
+      client.objects.update(class_name: @collection_name, id: id, properties: properties)
+    end
+
+    def delete_call(id)
+      client.objects.delete(class_name: @collection_name, id: id)
+    end
+
+    def check_existence(id)
+      client.objects.exists?(class_name: @collection_name, id: id)
+    end
+
+    def delete_where(condition)
+      client.objects.batch_delete(class_name: @collection_name, where: condition)
+    end
+  end
+end

data/lib/weaviate_record/constants.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module WeaviateRecord
+  module Constants # :nodoc:
+    SPECIAL_ATTRIBUTE_MAPPINGS = { 'feature_projection' => 'featureProjection',
+                                   'created_at' => 'creationTimeUnix',
+                                   'updated_at' => 'lastUpdateTimeUnix',
+                                   'explain_score' => 'explainScore' }.freeze
+
+    OPERATOR_MAPPING_HASH = { '=' => 'Equal', '==' => 'Equal', '!=' => 'NotEqual',
+                              '>' => 'GreaterThan', '<' => 'LessThan', '>=' => 'GreaterThanEqual',
+                              '<=' => 'LessThanEqual', 'LIKE' => 'Like', 'CONTAINS_ANY' => 'ContainsAny',
+                              'CONTAINS_ALL' => 'ContainsAll' }.freeze
+
+    TYPE_MAPPING_HASH = { Integer => 'valueInt', String => 'valueText', Array => 'valueText',
+                          Float => 'valueNumber', TrueClass => 'valueBoolean', FalseClass => 'valueBoolean' }.freeze
+
+    META_ATTRIBUTES = %w[vector certainty distance feature_projection classification
+                         creation_at updated_at score explain_score summary].freeze
+
+    UUID_REGEX = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i.freeze
+  end
+end
+
+WeaviateRecord::Constants.freeze

data/lib/weaviate_record/errors.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module WeaviateRecord # :nodoc: all
+  module Errors
+    # Used when an un-queried attribute is accessed
+    class MissingAttributeError < StandardError
+    end
+
+    # Used when an undefined attribute is accessed
+    class InvalidAttributeError < StandardError
+    end
+
+    # Used when a collection is not found in the schema
+    class CollectionNotFound < StandardError
+    end
+
+    # Used when a record without id is updated
+    class MissingIdError < StandardError
+    end
+
+    # Used when a custom queried record is updated
+    class CustomQueriedRecordError < StandardError
+    end
+
+    # Used when a meta attribute is updated
+    class MetaAttributeError < StandardError
+    end
+
+    # Used when there is a problem with Weaviate
+    class InternalError < StandardError
+    end
+
+    # Used when the Sorting order is invalid
+    class SortingOptionError < StandardError
+    end
+
+    # Used when the where query is invalid
+    class InvalidWhereQueryError < StandardError
+    end
+
+    # Used when the operator in where query is invalid
+    class InvalidOperatorError < StandardError
+    end
+
+    # Used when the value type in where query is invalid
+    class InvalidValueTypeError < StandardError
+    end
+
+    # Used when the record not found
+    class RecordNotFoundError < StandardError
+    end
+
+    # Used for the errors thrown by weaviate server
+    class ServerError < StandardError
+    end
+
+    # Used when destroy_all called without where conditions
+    class MissingWhereCondition < StandardError
+    end
+
+    # Raised when where condition is not getting converted to Ruby hash
+    class WhereQueryConversionError < StandardError
+    end
+
+    # Raised when required argument is empty
+    class EmptyPrompt < StandardError
+    end
+  end
+end

data/lib/weaviate_record/inspect.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module WeaviateRecord
+  module Inspect # :nodoc:
+    def inspect
+      special_attributes, inspection = format_attributes
+      string = to_s
+      string[-1] = ' '
+      string << "id: #{special_attributes['id'].inspect} " << inspection
+      string << " created_at: #{special_attributes['created_at'].inspect}" if special_attributes.key? 'created_at'
+      string << " updated_at: #{special_attributes['updated_at'].inspect}" if special_attributes.key? 'updated_at'
+      string << '>'
+    end
+
+    private
+
+    def format_attributes
+      attributes_list = { **@meta_attributes, **@attributes }
+      special_attributes = attributes_list.slice('id', 'created_at', 'updated_at')
+      attributes_list.except!(*special_attributes.keys)
+      inspection = attributes_list.sort.map do |key, value|
+        format_for_inspect(key, value)
+      end.join(', ')
+      [special_attributes, inspection]
+    end
+
+    def format_for_inspect(key, value)
+      formatted_value = case value
+                        when String then value.truncate(25).inspect
+                        when Array then key == 'vector' ? "[#{value.first(4).join(', ')}...]" : value.inspect
+                        else value.inspect
+                        end
+      "#{key.underscore}: #{formatted_value}"
+    end
+  end
+end

data/lib/weaviate_record/method_missing.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module WeaviateRecord
+  module MethodMissing # :nodoc:
+    private
+
+    def list_of_all_attributes
+      [*WeaviateRecord::Schema.find_collection(collection_name).attributes_list,
+       *WeaviateRecord::Constants::META_ATTRIBUTES]
+    end
+
+    def method_missing(method, *args, &block)
+      if list_of_all_attributes.include? method.to_s
+        raise WeaviateRecord::Errors::MissingAttributeError, "missing attribute: #{method}"
+      end
+
+      super
+    end
+
+    def respond_to_missing?(method, include_all = false)
+      list_of_all_attributes.include?(method.to_s) ? true : super
+    end
+  end
+end

data/lib/weaviate_record/queries/ask.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module WeaviateRecord
+  module Queries # :nodoc:
+    # This module provides method for ask query
+    module Ask
+      # Answers the question using the QnA module with the help of the records in the database.
+      #
+      # Requires QNA_INFERENCE_API to be set in the weaviate instance.
+      # The answer will be available in the _result_ key of the _answer_ meta attribute.
+      #
+      # You can also optionally pass an array of attributes to searched for the answer.
+      #
+      # ==== Example:
+      #   Article.create(content: 'the name is Sparrow')
+      #   Article.select(_additional: { answer: :result }).ask('whats your name?')
+      #   # => [#<Article:0x0000000109a85de0 id: nil answer: {"result"=>"Sparrow"}>]
+      def ask(question, on_attributes: [])
+        question.to_str
+        raise WeaviateRecord::Errors::EmptyPrompt, 'text cannot be empty' if question.empty?
+
+        attributes = on_attributes.map(&:to_s)
+        @ask = "{ question: #{question.gsub('"', "'").inspect}" \
+               "#{", properties: #{attributes}" if attributes.present?} }"
+        @loaded = false
+        self
+      end
+    end
+  end
+end

data/lib/weaviate_record/queries/bm25.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module WeaviateRecord
+  module Queries
+    # Bm25 is an algorithm to perform keyword based search on collection provided by Weaviate
+    # This class contains functions to perform that query
+    module Bm25
+      # Perform a keyword based search on the collection.
+      # You can also optionally pass an array of attributes to search in the collection.
+      #
+      # ==== Example:
+      #   Article.create(content: 'This is a movie about friendship, action and adventure')
+      #   # => #<Article:0x00000001052091e8 id: "983c0970-2c65-4c38-a93f-2ca9272d784b"... >
+      #
+      #   Article.bm25('friendship movie')
+      #   # => [#<Article:0x00000001052091e8 id: "983c0970-2c65-4c38-a93f-2ca9272d784b"... >]
+      def bm25(text, on_attributes: [])
+        text = text.to_str
+        return self if text.empty?
+
+        attributes = on_attributes.map(&:to_s)
+        @keyword_search = "{ query: #{text.gsub('"', "'").inspect}" \
+                          "#{", properties: #{attributes}" if attributes.present?} }"
+        @loaded = false
+        self
+      end
+    end
+  end
+end