stretchy-model 0.6.5 → 0.7.0

data/lib/stretchy/delegation/gateway_delegation.rb

@@ -18,6 +18,33 @@ module Stretchy
                 :count,
         to: :gateway
 
+      # This method is used to set or retrieve the index name for the Elasticsearch index.
+      #
+      # ### Parameters
+      #
+      # - `name:` (String, nil) - The name to set for the index. If nil, the method will act as a getter.
+      # - `&block:` A block that returns the index name when called.
+      #
+      # ### Returns
+      #
+      # - (String) - The index name.
+      #
+      # ### Behavior
+      #
+      # - If a name or block is provided, it sets the index name to the provided name or block.
+      # - If no argument is provided, it retrieves the index name. 
+      # - If the index name is callable (e.g., a Proc), it calls the block.
+      # - If the index name is not set, it defaults to the parameterized and underscored collection name of the base class model.
+      #
+      # ### Example
+      #
+      # In this example, the index name for instances of `MyModel` will be "my_custom_index" instead of "my_models".
+      #
+      # ```ruby
+      # class MyModel < Stretchy::Record
+      #   index_name "my_custom_index"
+      # end
+      # ```
       def index_name(name=nil, &block)
           if name || block_given?
             return (@index_name = name || block)
@@ -30,6 +57,30 @@ module Stretchy
           end
       end
 
+      # This method is used to set or retrieve the settings for the Elasticsearch index.
+      #
+      # ### Parameters
+      #
+      # - `settings:` (Hash) - The settings to set for the index. If empty, the method will act as a getter.
+      #
+      # ### Returns
+      #
+      # - (Hash) - The index settings.
+      #
+      # ### Behavior
+      #
+      # - If settings are provided, it sets the index settings to the provided settings.
+      # - If no argument is provided, it retrieves the index settings. 
+      # - If the `default_pipeline` is set, it merges it into the index settings.
+      #
+      # ### Example
+      #
+      # ```ruby
+      # class MyModel < Stretchy::Record
+      #   index_settings number_of_shards: 5, number_of_replicas: 1
+      # end
+      # ```
+      # In this example, the index settings for instances of `MyModel` will have 5 shards and 1 replica.
       def index_settings(settings={})
         @index_settings ||= settings
         @index_settings.merge!(default_pipeline: default_pipeline.to_s) if default_pipeline
@@ -40,6 +91,33 @@ module Stretchy
         @gateway = nil
       end
 
+      # This method is used to access the underlying `Stretchy::Repository` for the model. It creates the repository if it doesn't exist, and reuses it if it does.
+      #
+      # ### Parameters
+      #
+      # - `&block:` (optional) A block that is evaluated in the context of the repository. This can be used to perform operations on the repository.
+      #
+      # ### Returns
+      #
+      # - (Stretchy::Repository) - The repository for the model.
+      #
+      # ### Behavior
+      #
+      # - If the repository doesn't exist or if the client of the existing repository is not the current client from the Stretchy configuration, 
+      #   it creates a new repository with the current `client`, `index_name`, `class`, `mapping`, and `settings`.
+      # - If a block is given, it is evaluated in the context of the repository.
+      # - It always returns the repository.
+      #
+      # ### Example
+      #
+      # ```ruby
+      # class MyModel < Stretchy::Record
+      #   gateway do
+      #     # Perform operations on the repository
+      #   end
+      # end
+      # ```
+      #
       def gateway(&block)
           reload_gateway_configuration! if @gateway && @gateway.client != Stretchy.configuration.client
 

data/lib/stretchy/index_setting.rb

@@ -0,0 +1,94 @@
+module Stretchy
+  # This class is used to define settings for an Elasticsearch index. 
+  # It provides methods to define analyzers, filters, tokenizers, and normalizers.
+  #
+  # ## Usage
+  # ```ruby
+  # class MyIndexSetting < Stretchy::IndexSetting
+  #   analyzer :default, 
+  #            filter: [:lowercase, :asciifolding],
+  #            tokenizer: :standard
+  #
+  #   filter :my_stemmer,
+  #          type: :stemmer,
+  #          name: :light_english
+  #
+  #   tokenizer :path_tokenizer, 
+  #             type: :path_hierarchy,
+  #             reverse: true
+  #
+  #   normalizer :my_normalizer, 
+  #              type: :custom,
+  #              filter: [:lowercase]
+  # end
+  # ```
+  #
+  # In this example, we define a custom index setting `MyIndexSetting` that includes a default analyzer, a custom filter, a custom tokenizer, and a custom normalizer.
+  #
+  # ## Methods
+  # - `analyzer(name, options)`: Defines an analyzer with the given name and options.
+  # - `filter(name, options)`: Defines a filter with the given name and options.
+  # - `tokenizer(name, options)`: Defines a tokenizer with the given name and options.
+  # - `normalizer(name, options)`: Defines a normalizer with the given name and options.
+  #
+  # Each of these methods takes a name as the first argument and a hash of options as the second argument. The options will depend on the specific type of analyzer, filter, tokenizer, or normalizer being defined.
+  #
+  # ### Accessing Defined Settings
+  # You can access the settings defined in an `IndexSetting` subclass using the `analyzers`, `filters`, `tokenizers`, and `normalizers` methods. These methods return a hash of the defined settings for their respective type.
+  #
+  # ```ruby
+  #  MyIndexSetting.analyzers
+  #  # => { default: { filter: [:lowercase, :asciifolding], tokenizer: :standard } }
+  # ```
+  #
+  # ```ruby
+  #  MyIndexSetting.filters
+  #  # => { my_stemmer: { type: :stemmer, name: :light_english } }
+  # ```
+  #
+  # ```ruby
+  #  MyIndexSetting.tokenizers
+  #  # => { path_tokenizer: { type: :path_hierarchy, reverse: true } }
+  # ```
+  #
+  # ```ruby
+  #  MyIndexSetting.normalizers
+  #  # => { my_normalizer: { type: :custom, filter: [:lowercase] } }
+  # ```
+  # ### Using the Settings
+  # You can use the settings defined in an `IndexSetting` subclass to configure the settings for a `StretchyModel`.
+  #
+  # ```ruby
+  # class MyModel < StretchyModel
+  #  index_settings(MyIndexSetting.as_json)
+  # end
+  # ```
+  #
+  class IndexSetting
+    class << self
+      METHODS = [:analyzer, :filter, :tokenizer, :normalizer]
+
+      def settings
+        @settings ||= {}
+      end
+
+      def as_json
+        {
+          self.name.demodulize.underscore.to_sym => settings
+        }
+      end
+
+      METHODS.each do |method|
+        define_method(method) do |*args|
+          settings[method] ||= {}
+          settings[method][args.shift] = Hash[*args] unless args.empty?
+        end
+
+        define_method("#{method}s") do
+          settings[method] || {}
+        end
+      end
+
+    end
+  end
+end

data/lib/stretchy/indexing/bulk.rb

@@ -4,15 +4,62 @@ module Stretchy
             extend ActiveSupport::Concern
 
             class_methods do
-
+                # used to bulk index a collection of records.
+                #
+                # ### Parameters
+                #
+                # - `records:` (Array) - The collection of records to be indexed.
+                #
+                # ### Returns
+                #
+                # - (Hash) - The response from Elasticsearch after performing the bulk operation.
+                #
+                # ### Behavior
+                #
+                # The method sends a bulk request to Elasticsearch with the provided records. The records should be an array of hashes, where each hash describes a single create, index, delete, or update operation.
+                # It always returns the response from Elasticsearch.
+                #
+                # ### Example
+                #
+                # ```ruby
+                # records = [
+                #   { index: { _index: 'my_index', _id: 1, data: { title: 'foo' } } },
+                #   { index: { _index: 'my_index', _id: 2, data: { title: 'bar' } } }
+                # ]
+                # MyModel.bulk(records)
+                # ```
+                # In this example, the `bulk` method is used to index two records into 'my_index'.
                 def bulk(records)
                     self.gateway.client.bulk body: records
                 end
 
-                # bulk_in_batches(records, size: 100) do |batch|
+                # used to bulk index a collection of records in batches.
+                #
+                # ### Parameters
+                #
+                # - `records:` (Array) - The collection of records to be indexed.
+                # - `size:` (Integer) - The size of the batches. Defaults to 1000.
+                # - `&block:` (optional) A block that is evaluated for each batch. This can be used to perform operations on each batch.
+                #
+                # ### Returns
+                #
+                # - (Array) - The results of the bulk operations.
+                #
+                # ### Behavior
+                #
+                # - The method splits the records into batches of the specified size. For each batch, if a block is given, it is evaluated with the batch as argument. Then, the batch is indexed using the `bulk` method.
+                # - After all batches have been processed, it refreshes the index to make the changes available for search.
+                #
+                # ### Example
+                #
+                # ```ruby
+                # records = [Report.new(title: "hello"), Report.new(title: "world"), Report.new(title: "goodbye")]
+                # MyModel.bulk_in_batches(records, size: 100) do |batch|
                 #   # do something with the batch
-                #   batch.each { |record| record.to_bulk(method)}
+                #   batch.map! { |record| record.to_bulk(:index)}
                 # end
+                # ```
+                # In this example, the `bulk_in_batches` method is used to index the `records` in batches of 100. 
                 def bulk_in_batches(records, size: 1000)
                     bulk_results = records.each_slice(size).map do |batch|
                         yield batch if block_given?
@@ -32,6 +79,31 @@ module Stretchy
                 # end
             end
 
+            # used to transform a record into a hash suitable for bulk operations.
+            #
+            # ### Parameters
+            #
+            # - `method:` (Symbol) - The operation to be performed. Can be `:index`, `:delete`, or `:update`. Defaults to `:index`.
+            #
+            # ### Returns
+            #
+            # - (Hash) - The hash representing the record for the bulk operation.
+            #
+            # ### Behavior
+            #
+            # The method transforms the record into a hash that describes the operation to be performed on the record. The operation is specified by the `method` parameter.
+            # For `:index`, it includes the index name and the record data (excluding the id).
+            # For `:delete`, it includes the index name and the record id.
+            # For `:update`, it includes the index name, the record id, and the record data (excluding the id).
+            #
+            # ### Example
+            #
+            # ```ruby
+            # record = MyModel.new(title: "hello")
+            # record.to_bulk(:index)
+            # # => { index: { _index: "my_models", data: { title: "hello" } } }
+            # ```
+            # In this example, the `to_bulk` method is used to transform a `MyModel` instance into a hash suitable for an index operation in a bulk request.
             def to_bulk(method = :index)
                 case method
                 when :index

data/lib/stretchy/machine_learning/connector.rb

@@ -0,0 +1,130 @@
+module Stretchy
+  module MachineLearning
+    class Connector
+
+      cattr_reader :client do 
+        Stretchy.configuration.client.connector
+      end
+
+      class Settings
+        def initialize(valid_keys = [])
+          @valid_keys = valid_keys
+          @settings = {}
+        end
+
+        def as_json(*)
+          @settings.as_json
+        end
+      
+        def method_missing(method, *args, &block)
+          if block_given?
+            @settings[method] = self.class.new.tap { |obj| obj.instance_eval(&block) }
+          elsif args.empty?
+            value = @settings[method]
+            value.is_a?(Hash) ? Elasticsearch::Model::HashWrapper[value] : value
+          elsif args.length == 1 && @valid_keys.empty? || @valid_keys.include?(method)
+            @settings[method] = args.first
+          else
+            super
+          end
+        end
+      
+        def respond_to_missing?(method, include_private = false)
+          @settings.key?(method) || super
+        end
+      end
+      
+      class << self
+        include Errors
+        
+        METHODS = [
+          :description,
+          :version,
+          :protocol,
+          :credentials,
+          :parameters,
+          :actions,
+          :name
+        ].freeze
+        
+        def settings
+          @settings ||= Settings.new(METHODS)
+        end
+    
+        delegate *METHODS, to: :settings
+
+        def name(name = nil)
+          settings.name(name) if name 
+          settings.name || to_s.split('::').last.underscore
+        end
+
+        def registry
+          @registery ||= Stretchy::MachineLearning::Registry.register(class_name: self.name, class_type: 'connector')
+        end
+
+        def id
+          @id || registry.model_id
+        end
+
+        concerning :API do
+          def create!
+            response = client.post(body: self.to_hash.as_json).with_indifferent_access
+            registry.update(model_id: response.dig(:connector_id))
+            @id = response.dig(:connector_id)
+          end
+
+          def delete!
+            begin
+              response = client.delete(connector_id: self.id).with_indifferent_access
+            rescue "#{Stretchy.configuration.search_backend_const}::Transport::Transport::Errors::NotFound".constantize => e
+              raise Stretchy::MachineLearning::Errors::ConnectorMissingError
+              
+            ensure
+              if response.dig(:result) == 'deleted'
+                registry.delete
+                @registry = nil
+                @id = nil
+              end
+              response
+            end
+          end
+
+          def update!
+            client.put(connector_id: self.id, body: self.to_hash)
+          end
+
+          def find(id = nil)
+            begin
+              id = self.id if id.nil?
+              client.get(connector_id: id)
+            rescue ArgumentError => e
+              raise Stretchy::MachineLearning::Errors::ConnectorMissingError
+            rescue "#{Stretchy.configuration.search_backend_const}::Transport::Transport::Errors::NotFound".constantize => e
+              # raise Stretchy::MachineLearning::Errors::ConnectorMissingError
+            end
+          end
+
+          def exists?
+            self.find(self.id).present?
+          end
+
+          def to_hash
+            acts = self.actions.as_json
+            acts[:request_body] = actions[:request_body]
+            {
+              name: self.name,
+              description: self.description,
+              version: self.version,
+              protocol: self.protocol,
+              credential: self.credentials,
+              parameters: self.parameters,
+              actions: [acts]
+            }.compact
+
+          end
+        end
+     
+      end
+    end
+  end
+end

data/lib/stretchy/machine_learning/errors.rb

@@ -0,0 +1,25 @@
+module Stretchy::MachineLearning::Errors
+  class ModelNotDeployedError < StandardError
+    def initialize(msg="Model is not deployed. Please run `rake stretchy:ml:deploy` to deploy it.")
+      super
+    end
+  end
+
+  class ModelNotRegisteredError < StandardError
+    def initialize(msg="Model is not registered. Please run `rake stretchy:ml:register` to register it.")
+      super
+    end
+  end
+
+  class ConnectorMissingError < StandardError
+    def initialize(msg="Connector is missing. Please run `rake stretchy:ml:connector:create` to create it.")
+      super
+    end
+  end
+
+  class AgentNotRegisteredError < StandardError
+    def initialize(msg="Agent is not registered. Please run `rake stretchy:ml:agent:create` to create it.")
+      super
+    end
+  end
+end