mindee 3.19.1 → 4.0.0

data/lib/mindee/errors/mindee_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Errors
+    # Base class for all custom mindee errors.
+    class MindeeError < StandardError; end
+
+    # Errors relating to library issues.
+    class MindeeAPIError < MindeeError; end
+
+    # Errors relating to misuse of the library.
+    class MindeeConfigurationError < MindeeError; end
+
+    # Errors relating to geometric manipulation issues.
+    class MindeeGeometryError < MindeeError; end
+  end
+end

data/lib/mindee/errors/mindee_http_error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'mindee_error'
+
+module Mindee
+  module Errors
+    # API HttpError
+    class MindeeHTTPError < MindeeError
+      # @return [String]
+      attr_reader :status_code
+      # @return [Integer]
+      attr_reader :api_code
+      # @return [String]
+      attr_reader :api_details
+      # @return [String]
+      attr_reader :api_message
+
+      # @param http_error [Hash]
+      # @param url [String]
+      # @param code [Integer]
+      def initialize(http_error, url, code)
+        @status_code = code
+        @api_code = http_error['code']
+        @api_details = http_error['details']
+        @api_message = http_error['message']
+        super("#{url} #{@status_code} HTTP error: #{@api_details} - #{@api_message}")
+      end
+    end
+
+    # Base class for all client-side errors.
+    class MindeeHTTPClientError < MindeeHTTPError; end
+
+    # Base class for all server-side errors.
+    class MindeeHTTPServerError < MindeeHTTPError; end
+  end
+end

data/lib/mindee/errors/mindee_input_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Errors
+    # Base class for errors relating to input documents.
+    class MindeeInputError < MindeeError; end
+
+    # Errors relating to sources (documents) handling.
+    class MindeeSourceError < MindeeInputError; end
+
+    # Errors relating to mime type issues.
+    class MindeeMimeTypeError < MindeeSourceError
+      # @return [String]
+      attr_reader :invalid_mimetype
+
+      # @param mime_type [String]
+      def initialize(mime_type)
+        @invalid_mimetype = mime_type
+        super("'#{@invalid_mimetype}' mime type not allowed, must be one of" \
+              "#{Mindee::Input::Source::ALLOWED_MIME_TYPES.join(', ')}")
+      end
+    end
+
+    # Errors relating to the handling of images.
+    class MindeeImageError < MindeeInputError; end
+
+    # Errors relating to the handling of PDF documents.
+    class MindeePDFError < MindeeInputError; end
+  end
+end

data/lib/mindee/errors.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'errors/mindee_error'
+require_relative 'errors/mindee_http_error'
+require_relative 'errors/mindee_input_error'

data/lib/mindee/extraction/multi_receipts_extractor.rb

@@ -1,3 +1,30 @@
 # frozen_string_literal: true
 
-require_relative 'multi_receipts_extractor/multi_receipts_extractor'
+module Mindee
+  # Custom extraction module
+  module Extraction
+    # Multi-receipts extraction
+    # Extracts individual receipts from multi-receipts documents.
+    #
+    # @param input_source [LocalInputSource] Local Input Source to extract sub-receipts from.
+    # @param inference [Inference] Results of the inference.
+    # @return [Array<ExtractedImage>] Individual extracted receipts as an array of ExtractedMultiReceiptsImage.
+    def self.extract_receipts(input_source, inference)
+      images = []
+      unless inference.prediction.receipts
+        raise Errors::MindeeInputError,
+              'No possible receipts candidates found for Multi-Receipts extraction.'
+      end
+
+      (0...input_source.count_pages).each do |page_id|
+        receipt_positions = inference.pages[page_id].prediction.receipts.map(&:bounding_box)
+        images.concat(
+          Mindee::Image::ImageExtractor.extract_multiple_images_from_source(input_source, page_id + 1,
+                                                                            receipt_positions)
+        )
+      end
+
+      images
+    end
+  end
+end

data/lib/mindee/extraction.rb

@@ -1,6 +1,3 @@
 # frozen_string_literal: true
 
-require_relative 'extraction/tax_extractor'
 require_relative 'extraction/multi_receipts_extractor'
-require_relative 'extraction/common'
-require_relative 'extraction/pdf_extractor'

data/lib/mindee/geometry/polygon.rb

@@ -13,7 +13,7 @@ module Mindee
 
       # Determine if the Point is in the Polygon's Y-axis.
       # @param point [Mindee::Geometry::Point]
-      # @return [Boolean]
+      # @return [bool]
       def point_in_y?(point)
         min_max = Geometry.get_min_max_y(self)
         min_max.min <= point.y && point.y <= min_max.max

data/lib/mindee/geometry/utils.rb

@@ -4,7 +4,7 @@ module Mindee
   # Various helper functions for geometry.
   module Geometry
     # Transform a prediction into a Quadrilateral.
-    # @param prediction [Hash]
+    # @param prediction [Array<Array<Float>>]
     # @return [Mindee::Geometry::Quadrilateral]
     def self.quadrilateral_from_prediction(prediction)
       throw "Prediction must have exactly 4 points, found #{prediction.size}" if prediction.size != 4

data/lib/mindee/http/endpoint.rb

@@ -2,7 +2,7 @@
 
 require 'json'
 require 'net/http'
-require_relative 'error'
+require_relative 'http_error_handler'
 require_relative '../version'
 require_relative 'response_validation'
 
@@ -24,7 +24,7 @@ module Mindee
     TIMEOUT_DEFAULT = 120
 
     # Default value for the user agent.
-    USER_AGENT = "mindee-api-ruby@v#{Mindee::VERSION} ruby-v#{RUBY_VERSION} #{Mindee::PLATFORM}"
+    USER_AGENT = "mindee-api-ruby@v#{Mindee::VERSION} ruby-v#{RUBY_VERSION} #{Mindee::PLATFORM}".freeze
 
     # Generic API endpoint for a product.
     class Endpoint
@@ -40,17 +40,20 @@ module Mindee
         @url_name = url_name
         @version = version
         @request_timeout = ENV.fetch(REQUEST_TIMEOUT_ENV_NAME, TIMEOUT_DEFAULT).to_i
+        if api_key.nil? && !ENV.fetch(API_KEY_ENV_NAME, API_KEY_DEFAULT).to_s.empty?
+          logger.debug('API key set from environment')
+        end
         @api_key = api_key.nil? || api_key.empty? ? ENV.fetch(API_KEY_ENV_NAME, API_KEY_DEFAULT) : api_key
         base_url = ENV.fetch(BASE_URL_ENV_NAME, BASE_URL_DEFAULT)
         @url_root = "#{base_url.chomp('/')}/products/#{@owner}/#{@url_name}/v#{@version}"
       end
 
       # Call the prediction API.
-      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
-      # @param all_words [Boolean] Whether the full word extraction needs to be performed
-      # @param full_text [Boolean] Whether to include the full OCR text response in compatible APIs
-      # @param close_file [Boolean] Whether the file will be closed after reading
-      # @param cropper [Boolean] Whether a cropping operation will be applied
+      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
+      # @param all_words [bool] Whether the full word extraction needs to be performed
+      # @param full_text [bool] Whether to include the full OCR text response in compatible APIs
+      # @param close_file [bool] Whether the file will be closed after reading
+      # @param cropper [bool] Whether a cropping operation will be applied
       # @return [Array]
       def predict(input_source, all_words, full_text, close_file, cropper)
         check_api_key
@@ -61,29 +64,34 @@ module Mindee
           close_file: close_file,
           cropper: cropper
         )
-        hashed_response = JSON.parse(response.body, object_class: Hash)
-        return [hashed_response, response.body] if ResponseValidation.valid_sync_response?(response)
+        if !response.nil? && response.respond_to?(:body)
+          hashed_response = JSON.parse(response.body, object_class: Hash)
+          return [hashed_response, response.body] if ResponseValidation.valid_sync_response?(response)
 
-        ResponseValidation.clean_request!(response)
-        error = Error.handle_error(@url_name, response)
+          ResponseValidation.clean_request!(response)
+        end
+        error = ErrorHandler.handle_error(@url_name, response)
         raise error
       end
 
       # Call the prediction API.
-      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
-      # @param all_words [Boolean] Whether the full word extraction needs to be performed
-      # @param full_text [Boolean] Whether to include the full OCR text response in compatible APIs.
-      # @param close_file [Boolean] Whether the file will be closed after reading
-      # @param cropper [Boolean] Whether a cropping operation will be applied
+      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
+      # @param all_words [bool] Whether the full word extraction needs to be performed
+      # @param full_text [bool] Whether to include the full OCR text response in compatible APIs.
+      # @param close_file [bool] Whether the file will be closed after reading
+      # @param cropper [bool] Whether a cropping operation will be applied
       # @return [Array]
       def predict_async(input_source, all_words, full_text, close_file, cropper)
         check_api_key
         response = document_queue_req_get(input_source, all_words, full_text, close_file, cropper)
-        hashed_response = JSON.parse(response.body, object_class: Hash)
-        return [hashed_response, response.body] if ResponseValidation.valid_async_response?(response)
+        if !response.nil? && response.respond_to?(:body)
+          hashed_response = JSON.parse(response.body, object_class: Hash)
+          return [hashed_response, response.body] if ResponseValidation.valid_async_response?(response)
 
-        ResponseValidation.clean_request!(response)
-        error = Error.handle_error(@url_name, response)
+          ResponseValidation.clean_request!(response)
+        end
+
+        error = ErrorHandler.handle_error(@url_name, response)
         raise error
       end
 
@@ -97,22 +105,22 @@ module Mindee
         return [hashed_response, response.body] if ResponseValidation.valid_async_response?(response)
 
         ResponseValidation.clean_request!(response)
-        error = Error.handle_error(@url_name, response)
+        error = ErrorHandler.handle_error(@url_name, response)
         raise error
       end
 
       private
 
-      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
-      # @param all_words [Boolean] Whether the full word extraction needs to be performed
-      # @param full_text [Boolean] Whether to include the full OCR text response in compatible APIs.
-      # @param close_file [Boolean] Whether the file will be closed after reading
-      # @param cropper [Boolean] Whether a cropping operation will be applied
+      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
+      # @param all_words [bool] Whether the full word extraction needs to be performed
+      # @param full_text [bool] Whether to include the full OCR text response in compatible APIs.
+      # @param close_file [bool] Whether the file will be closed after reading
+      # @param cropper [bool] Whether a cropping operation will be applied
       # @return [Net::HTTPResponse, nil]
       def predict_req_post(input_source, all_words: false, full_text: false, close_file: true, cropper: false)
         uri = URI("#{@url_root}/predict")
 
-        params = {}
+        params = {} # : Hash[Symbol | String, untyped]
         params[:cropper] = 'true' if cropper
         params[:full_text_ocr] = 'true' if full_text
         uri.query = URI.encode_www_form(params)
@@ -122,10 +130,10 @@ module Mindee
           'User-Agent' => USER_AGENT,
         }
         req = Net::HTTP::Post.new(uri, headers)
-        form_data = if input_source.is_a?(Mindee::Input::Source::UrlInputSource)
+        form_data = if input_source.is_a?(Mindee::Input::Source::URLInputSource)
                       [['document', input_source.url]]
                     else
-                      [input_source.read_document(close: close_file)]
+                      [input_source.read_contents(close: close_file)]
                     end
         form_data.push ['include_mvision', 'true'] if all_words
 
@@ -137,16 +145,16 @@ module Mindee
         response
       end
 
-      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
-      # @param all_words [Boolean] Whether the full word extraction needs to be performed
-      # @param full_text [Boolean] Whether to include the full OCR text response in compatible APIs.
-      # @param close_file [Boolean] Whether the file will be closed after reading
-      # @param cropper [Boolean] Whether a cropping operation will be applied
+      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
+      # @param all_words [bool] Whether the full word extraction needs to be performed
+      # @param full_text [bool] Whether to include the full OCR text response in compatible APIs.
+      # @param close_file [bool] Whether the file will be closed after reading
+      # @param cropper [bool] Whether a cropping operation will be applied
       # @return [Net::HTTPResponse, nil]
       def document_queue_req_get(input_source, all_words, full_text, close_file, cropper)
         uri = URI("#{@url_root}/predict_async")
 
-        params = {}
+        params = {} # : Hash[Symbol | String, untyped]
         params[:cropper] = 'true' if cropper
         params[:full_text_ocr] = 'true' if full_text
         uri.query = URI.encode_www_form(params)
@@ -156,10 +164,10 @@ module Mindee
           'User-Agent' => USER_AGENT,
         }
         req = Net::HTTP::Post.new(uri, headers)
-        form_data = if input_source.is_a?(Mindee::Input::Source::UrlInputSource)
+        form_data = if input_source.is_a?(Mindee::Input::Source::URLInputSource)
                       [['document', input_source.url]]
                     else
-                      [input_source.read_document(close: close_file)]
+                      [input_source.read_contents(close: close_file)]
                     end
         form_data.push ['include_mvision', 'true'] if all_words
 
@@ -201,9 +209,9 @@ module Mindee
       def check_api_key
         return unless @api_key.nil? || @api_key.empty?
 
-        raise "Missing API key for product \"'#{@url_name}' v#{@version}\" (belonging to \"#{@owner}\"), " \
-              "check your Client Configuration.\n" \
-              'You can set this using the ' \
+        raise Errors::MindeeAPIError,
+              "Missing API key for product \"'#{@url_name}' v#{@version}\" (belonging to \"#{@owner}\"), " \
+              "check your Client Configuration.\nYou can set this using the " \
               "'#{HTTP::API_KEY_ENV_NAME}' environment variable."
       end
     end

data/lib/mindee/http/{error.rb → http_error_handler.rb}

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 require 'json'
+require_relative '../errors/mindee_http_error'
 
 module Mindee
   module HTTP
     # Mindee HTTP error module.
-    module Error
+    module ErrorHandler
       module_function
 
       # Extracts the HTTP error from the response hash, or the job error if there is one.
@@ -80,44 +81,13 @@ module Mindee
         error_obj = create_error_obj(parsed_hash)
         case code
         when 400..499
-          MindeeHttpClientError.new(error_obj, url, code)
+          Errors::MindeeHTTPClientError.new(error_obj, url, code)
         when 500..599
-          MindeeHttpServerError.new(error_obj, url, code)
+          Errors::MindeeHTTPServerError.new(error_obj, url, code)
         else
-          MindeeHttpError.new(error_obj, url, code)
+          Errors::MindeeHTTPError.new(error_obj, url, code)
         end
       end
-
-      # API HttpError
-      class MindeeHttpError < StandardError
-        # @return [String]
-        attr_reader :status_code
-        # @return [Integer]
-        attr_reader :api_code
-        # @return [String]
-        attr_reader :api_details
-        # @return [String]
-        attr_reader :api_message
-
-        # @param http_error [Hash]
-        # @param url [String]
-        # @param code [Integer]
-        def initialize(http_error, url, code)
-          @status_code = code
-          @api_code = http_error['code']
-          @api_details = http_error['details']
-          @api_message = http_error['message']
-          super("#{url} #{@status_code} HTTP error: #{@api_details} - #{@api_message}")
-        end
-      end
-
-      # API client HttpError
-      class MindeeHttpClientError < MindeeHttpError
-      end
-
-      # API server HttpError
-      class MindeeHttpServerError < MindeeHttpError
-      end
     end
   end
 end

data/lib/mindee/http/response_validation.rb

@@ -9,7 +9,7 @@ module Mindee
     module ResponseValidation
       # Checks if the synchronous response is valid. Returns True if the response is valid.
       # @param [Net::HTTPResponse] response
-      # @return [Boolean]
+      # @return [bool]
       def self.valid_sync_response?(response)
         return false unless (200..399).cover?(response.code.to_i)
 
@@ -24,7 +24,7 @@ module Mindee
       # Checks if the asynchronous response is valid. Also checks if it is a valid synchronous response.
       # Returns true if the response is valid.
       # @param [Net::HTTPResponse] response
-      # @return [Boolean]
+      # @return [bool]
       def self.valid_async_response?(response)
         return false unless valid_sync_response?(response)
 

data/lib/mindee/http/workflow_endpoint.rb

@@ -2,7 +2,7 @@
 
 require 'json'
 require 'net/http'
-require_relative 'error'
+require_relative 'http_error_handler'
 
 module Mindee
   module HTTP
@@ -23,10 +23,10 @@ module Mindee
       end
 
       # Sends a document to the workflow.
-      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
+      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
       # @param document_alias [String, nil] Alias to give to the document.
       # @param priority [Symbol, nil] Priority to give to the document.
-      # @param full_text [Boolean] Whether to include the full OCR text response in compatible APIs.
+      # @param full_text [bool] Whether to include the full OCR text response in compatible APIs.
       # @param public_url [String, nil] A unique, encrypted URL for accessing the document validation interface without
       # requiring authentication.
       # @return [Array]
@@ -37,20 +37,20 @@ module Mindee
         return [hashed_response, response.body] if ResponseValidation.valid_async_response?(response)
 
         ResponseValidation.clean_request!(response)
-        error = Error.handle_error(@url_name, response)
+        error = Mindee::HTTP::ErrorHandler.handle_error(@url_name, response)
         raise error
       end
 
-      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
+      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
       # @param document_alias [String, nil] Alias to give to the document.
       # @param priority [Symbol, nil] Priority to give to the document.
-      # @param full_text [Boolean] Whether to include the full OCR text response in compatible APIs.
+      # @param full_text [bool] Whether to include the full OCR text response in compatible APIs.
       # @param public_url [String, nil] A unique, encrypted URL for accessing the document validation interface without
       # requiring authentication.
       # @return [Net::HTTPResponse, nil]
       def workflow_execution_req_post(input_source, document_alias, priority, full_text, public_url)
         uri = URI(@url)
-        params = {}
+        params = {} # : Hash[Symbol | String, untyped]
         params[:full_text_ocr] = 'true' if full_text
         uri.query = URI.encode_www_form(params)
 
@@ -59,10 +59,10 @@ module Mindee
           'User-Agent' => USER_AGENT,
         }
         req = Net::HTTP::Post.new(uri, headers)
-        form_data = if input_source.is_a?(Mindee::Input::Source::UrlInputSource)
+        form_data = if input_source.is_a?(Mindee::Input::Source::URLInputSource)
                       [['document', input_source.url]]
                     else
-                      [input_source.read_document]
+                      [input_source.read_contents]
                     end
         form_data.push ['alias', document_alias] if document_alias
         form_data.push ['public_url', public_url] if public_url
@@ -81,9 +81,9 @@ module Mindee
       def check_api_key
         return unless @api_key.nil? || @api_key.empty?
 
-        raise "Missing API key. Check your Client Configuration.\n" \
-              'You can set this using the ' \
-              "'#{HTTP::API_KEY_ENV_NAME}' environment variable."
+        raise Errors::MindeeConfigurationError, "Missing API key. Check your Client Configuration.\n" \
+                                                "You can set this using the '#{HTTP::API_KEY_ENV_NAME}'" \
+                                                'environment variable.'
       end
     end
   end

data/lib/mindee/http.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 require_relative 'http/endpoint'
-require_relative 'http/error'
+require_relative 'http/http_error_handler'
 require_relative 'http/workflow_endpoint'

data/lib/mindee/{extraction/common → image}/extracted_image.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
-require_relative '../../input/sources'
+require_relative '../input/sources'
+require_relative '../logging'
 
 module Mindee
   # Image Extraction Module.
-  module Extraction
+  module Image
     # Generic class for image extraction.
     class ExtractedImage
-      # Id of the page the image was extracted from.
+      # ID of the page the image was extracted from.
       attr_reader :page_id
 
-      # Id of the element on a given page.
+      # ID of the element on a given page.
       attr_reader :element_id
 
       # Buffer object of the file's content.
@@ -25,14 +26,15 @@ module Mindee
       # @param page_id [Integer] ID of the page the element was found on.
       # @param element_id [Integer, nil] ID of the element in a page.
       def initialize(input_source, page_id, element_id)
-        @buffer = StringIO.new(input_source.io_stream.read)
+        @buffer = StringIO.new(input_source.io_stream.read.to_s)
         @buffer.rewind
         extension = if input_source.pdf?
-                      'jpg'
+                      '.jpg'
                     else
                       File.extname(input_source.filename)
                     end
-        @internal_file_name = "#{input_source.filename}_p#{page_id}_#{element_id}.#{extension}"
+        base_name = File.basename(input_source.filename, File.extname(input_source.filename))
+        @internal_file_name = "#{base_name}_p#{page_id}_#{element_id}#{extension}"
         @page_id = page_id
         @element_id = element_id.nil? ? 0 : element_id
       end
@@ -43,21 +45,23 @@ module Mindee
       # @param file_format [String, nil] Optional MiniMagick-compatible format for the file. Inferred from file
       # extension if not provided.
       # @raise [MindeeError] If an invalid path or filename is provided.
-      def save_to_file(output_path, file_format = nil)
-        resolved_path = Pathname.new(output_path).realpath
+      def write_to_file(output_path, file_format = nil)
+        resolved_path = Pathname.new(File.expand_path(output_path))
         if file_format.nil?
-          raise ArgumentError, 'Invalid file format.' if resolved_path.extname.delete('.').empty?
+          raise Errors::MindeeImageError, 'Invalid file format.' if resolved_path.extname.delete('.').empty?
 
           file_format = resolved_path.extname.delete('.').upcase
         end
-        @buffer.rewind
-        image = MiniMagick::Image.read(@buffer)
-        image.format file_format.downcase
-        image.write resolved_path.to_s
-      rescue TypeError
-        raise 'Invalid path/filename provided.'
-      rescue StandardError
-        raise "Could not save file #{Pathname.new(output_path).basename}."
+        begin
+          @buffer.rewind
+          image = MiniMagick::Image.read(@buffer)
+          image.format file_format.to_s.downcase
+          image.write resolved_path.to_s
+          logger.info("File saved successfully to '#{resolved_path}'")
+        rescue StandardError
+          raise Errors::MindeeImageError, "Could not save file '#{output_path}'. " \
+                                          'Is the provided file path valid?.'
+        end
       end
 
       # Return the file as a Mindee-compatible BufferInput source.