mindee 4.6.0 → 4.7.0.pre.rc2

data/lib/mindee/http/endpoint.rb

@@ -66,6 +66,9 @@ module Mindee
 
           ResponseValidation.clean_request!(response)
         end
+
+        raise Errors::MindeeError, 'Could not resolve server response.' if response.nil?
+
         error = ErrorHandler.handle_error(@url_name, response)
         raise error
       end
@@ -84,8 +87,9 @@ module Mindee
           ResponseValidation.clean_request!(response)
         end
 
-        error = ErrorHandler.handle_error(@url_name, response)
-        raise error
+        raise Errors::MindeeError, 'Could not resolve server response.' if response.nil?
+
+        raise ErrorHandler.handle_error(@url_name, response)
       end
 
       # Calls the parsed async doc.
@@ -110,7 +114,7 @@ module Mindee
       def predict_req_post(input_source, opts)
         uri = URI("#{@url_root}/predict")
 
-        params = {} # : Hash[Symbol | String, untyped]
+        params = {} # : Hash[String | Symbol, untyped]
         params[:cropper] = 'true' if opts.cropper
         params[:full_text_ocr] = 'true' if opts.full_text
         uri.query = URI.encode_www_form(params)
@@ -123,7 +127,7 @@ module Mindee
         form_data = if input_source.is_a?(Mindee::Input::Source::URLInputSource)
                       [['document', input_source.url]] # : Array[untyped]
                     else
-                      [input_source.read_contents(close: opts.close_file)] # : Array[untyped]
+                      [['document', *input_source.read_contents(close: opts.close_file)]] # : Array[untyped]
                     end
         form_data.push ['include_mvision', 'true'] if opts.all_words
 
@@ -146,7 +150,7 @@ module Mindee
                 URI("#{@url_root}/predict_async")
               end
 
-        params = {} # : Hash[Symbol | String, untyped]
+        params = {} # : Hash[String | Symbol, untyped]
         params[:cropper] = 'true' if opts.cropper
         params[:full_text_ocr] = 'true' if opts.full_text
         params[:rag] = 'true' if opts.rag
@@ -160,7 +164,7 @@ module Mindee
         form_data = if input_source.is_a?(Mindee::Input::Source::URLInputSource)
                       [['document', input_source.url]] # : Array[untyped]
                     else
-                      [input_source.read_contents(close: opts.close_file)] # : Array[untyped]
+                      [['document', *input_source.read_contents(close: opts.close_file)]] # : Array[untyped]
                     end
         form_data.push ['include_mvision', 'true'] if opts.all_words
 
@@ -189,6 +193,8 @@ module Mindee
           http.request(req)
         end
 
+        raise Errors::MindeeError, 'Could not resolve server response.' if response.nil?
+
         if response.code.to_i > 299 && response.code.to_i < 400
           req = Net::HTTP::Get.new(response['location'], headers)
           Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|

data/lib/mindee/http/http_error_handler.rb

@@ -65,7 +65,7 @@ module Mindee
                       end
 
         end
-        error_obj.nil? ? {} : error_obj
+        error_obj
       end
 
       # Creates an appropriate HTTP error exception, based on retrieved http error code
@@ -81,11 +81,24 @@ module Mindee
         error_obj = create_error_obj(parsed_hash)
         case code
         when 400..499
-          Errors::MindeeHTTPClientError.new(error_obj, url, code)
+          Errors::MindeeHTTPClientError.new(error_obj || {}, url, code)
         when 500..599
-          Errors::MindeeHTTPServerError.new(error_obj, url, code)
+          Errors::MindeeHTTPServerError.new(error_obj || {}, url, code)
         else
-          Errors::MindeeHTTPError.new(error_obj, url, code)
+          Errors::MindeeHTTPError.new(error_obj || {}, url, code)
+        end
+      end
+
+      # Creates an appropriate HTTP error exception for a V2 API response, based on retrieved http error code.
+      # @param hashed_response [Hash] dictionary response retrieved by the server
+      def generate_v2_error(hashed_response)
+        code = hashed_response[:code].to_i
+        if hashed_response.key?(:status)
+          Errors::MindeeHTTPErrorV2.new(hashed_response.transform_keys(&:to_s))
+        elsif code < 200 || code > 399
+          Errors::MindeeHTTPErrorV2.new({ 'status' => code, 'detail' => 'No details available.' })
+        else
+          Errors::MindeeHTTPErrorV2.new({ 'status' => -1, 'detail' => 'Unknown Error.' })
         end
       end
     end

data/lib/mindee/http/mindee_api_v2.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative 'api_settings_v2'
+require_relative '../input'
+require_relative '../errors'
+require_relative '../parsing/v2'
+
+module Mindee
+  module HTTP
+    # API client for version 2.
+    class MindeeApiV2
+      # @return [ApiSettingsV2]
+      attr_reader :settings
+
+      # @param api_key [String, nil]
+      def initialize(api_key: nil)
+        @settings = ApiSettingsV2.new(api_key: api_key)
+      end
+
+      # Sends a file to the inference queue.
+      #
+      # @param input_source [Input::Source::LocalInputSource, Input::Source::URLInputSource]
+      # @param params [Input::InferenceParameters]
+      # @return [Mindee::Parsing::V2::JobResponse]
+      # @raise [Mindee::Errors::MindeeHttpErrorV2]
+      def req_post_inference_enqueue(input_source, params)
+        @settings.check_api_key
+        response = enqueue(
+          input_source,
+          params
+        )
+        Parsing::V2::JobResponse.new(process_response(response))
+      end
+
+      # Retrieves a queued inference.
+      #
+      # @param inference_id [String]
+      # @return [Mindee::Parsing::V2::InferenceResponse]
+      def req_get_inference(inference_id)
+        @settings.check_api_key
+        response = inference_result_req_get(
+          inference_id
+        )
+        Parsing::V2::InferenceResponse.new(process_response(response))
+      end
+
+      # Retrieves a queued job.
+      #
+      # @param job_id [String]
+      # @return [Mindee::Parsing::V2::JobResponse]
+      def req_get_job(job_id)
+        @settings.check_api_key
+        response = inference_job_req_get(
+          job_id
+        )
+        Parsing::V2::JobResponse.new(process_response(response))
+      end
+
+      private
+
+      # Converts an HTTP response to a parsed response object.
+      #
+      # @param response [Net::HTTPResponse, nil]
+      # @return [Hash]
+      # @raise Throws if the server returned an error.
+      def process_response(response)
+        if !response.nil? && response.respond_to?(:body) && ResponseValidation.valid_v2_response?(response)
+          return JSON.parse(response.body, object_class: Hash)
+        end
+
+        response_body = if response.nil? || !response.respond_to?(:body)
+                          '{ "status": -1,
+                            "detail": "Empty server response." }'
+                        else
+                          response.body
+                        end
+        raise ErrorHandler.generate_v2_error(JSON.parse(response_body).transform_keys(&:to_sym))
+      end
+
+      # Polls a queue for either a result or a job.
+      # @param url [String] URL, passed as a string.
+      # @return [Net::HTTPResponse]
+      def poll(url)
+        uri = URI(url)
+        headers = {
+          'Authorization' => @settings.api_key,
+          'User-Agent' => @settings.user_agent,
+        }
+        req = Net::HTTP::Get.new(uri, headers)
+        req['Transfer-Encoding'] = 'chunked'
+
+        Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @settings.request_timeout) do |http|
+          return http.request(req)
+        end
+        raise Mindee::Errors::MindeeError, 'Could not resolve server response.'
+      end
+
+      # Polls the API for the status of a job.
+      #
+      # @param job_id [String] ID of the job.
+      # @return [Net::HTTPResponse]
+      def inference_job_req_get(job_id)
+        poll("#{@settings.base_url}/jobs/#{job_id}")
+      end
+
+      # Polls the API for the result of an inference.
+      #
+      # @param queue_id [String] ID of the queue.
+      # @return [Net::HTTPResponse]
+      def inference_result_req_get(queue_id)
+        poll("#{@settings.base_url}/inferences/#{queue_id}")
+      end
+
+      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
+      # @param params [Input::InferenceParameters] Parse options.
+      # @return [Net::HTTPResponse, nil]
+      def enqueue(input_source, params)
+        uri = URI("#{@settings.base_url}/inferences/enqueue")
+
+        form_data = if input_source.is_a?(Mindee::Input::Source::URLInputSource)
+                      [['url', input_source.url]] # : Array[untyped]
+                    else
+                      file_data, file_metadata = input_source.read_contents(close: params.close_file)
+                      [['file', file_data, file_metadata]] # : Array[untyped]
+                    end
+        form_data.push ['model_id', params.model_id]
+        form_data.push ['rag', 'true'] if params.rag
+        form_data.push ['file_alias', params.file_alias] if params.file_alias
+        unless params.webhook_ids.nil? || params.webhook_ids.empty?
+          form_data.push ['webhook_ids', params.webhook_ids.join(',')]
+        end
+        headers = {
+          'Authorization' => @settings.api_key,
+          'User-Agent' => @settings.user_agent,
+        }
+        req = Net::HTTP::Post.new(uri, headers)
+
+        req.set_form(form_data, 'multipart/form-data')
+        req['Transfer-Encoding'] = 'chunked'
+
+        Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @settings.request_timeout) do |http|
+          return http.request(req)
+        end
+        raise Mindee::Errors::MindeeError, 'Could not resolve server response.'
+      end
+    end
+  end
+end

data/lib/mindee/http/response_validation.rb

@@ -21,6 +21,25 @@ module Mindee
         true
       end
 
+      # Checks if a V2 response is valid.
+      # @param [Net::HTTPResponse] response
+      # @return [bool]
+      def self.valid_v2_response?(response)
+        return false unless valid_sync_response?(response)
+
+        hashed_response = JSON.parse(response.body, object_class: Hash)
+
+        return false if hashed_response.dig('job', 'status').to_s == 'Failed'
+
+        return false if hashed_response.dig('job',
+                                            'error') && !(hashed_response.dig('job',
+                                                                              'error').empty? || hashed_response.dig(
+                                                                                'job', 'error'
+                                                                              ).nil?)
+
+        true
+      end
+
       # 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
@@ -52,7 +71,7 @@ module Mindee
         end
 
         return if !hashed_response.dig('job', 'error').empty? &&
-                  (hashed_response.dig('job', 'status') != Mindee::Parsing::Common::JobStatus::FAILURE.to_s)
+                  (hashed_response.dig('job', 'status').downcase != Mindee::Parsing::Common::JobStatus::FAILURE.to_s)
 
         response.instance_variable_set(:@code, '500')
       end

data/lib/mindee/http/workflow_endpoint.rb

@@ -48,7 +48,7 @@ module Mindee
       # @return [Net::HTTPResponse, nil]
       def workflow_execution_req_post(input_source, opts)
         uri = URI(@url)
-        params = {} # : Hash[Symbol | String, untyped]
+        params = {} # : Hash[String | Symbol, untyped]
         params[:full_text_ocr] = 'true' if opts.full_text
         params[:rag] = 'true' if opts.rag
         uri.query = URI.encode_www_form(params) if params.any?
@@ -62,7 +62,7 @@ module Mindee
         if input_source.is_a?(Mindee::Input::Source::URLInputSource)
           form_data.push ['document', input_source.url]
         else
-          form_data.push input_source.read_contents
+          form_data.push ['document', *input_source.read_contents(close: opts.close_file)]
         end
         form_data.push ['alias', opts.document_alias] if opts.document_alias
         form_data.push ['public_url', opts.public_url] if opts.public_url

data/lib/mindee/http.rb

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

data/lib/mindee/image/extracted_image.rb

@@ -69,7 +69,7 @@ module Mindee
       # @return [FileInputSource] A BufferInput source.
       def as_source
         @buffer.rewind
-        Mindee::Input::Source::BytesInputSource.new(@buffer.read, @internal_file_name)
+        Mindee::Input::Source::BytesInputSource.new(@buffer.read || '', @internal_file_name)
       end
     end
   end

data/lib/mindee/image/image_extractor.rb

@@ -18,23 +18,20 @@ module Mindee
       # @return [Origami::PDF] A PdfDocument handle.
       def self.attach_image_as_new_file(input_buffer, format: 'jpg')
         magick_image = MiniMagick::Image.read(input_buffer)
-        # NOTE: some jpeg images get rendered as three different versions of themselves per output if the format isn't
-        # converted.
+        # NOTE: We force format consolidation to a single format to avoid frames being interpreted as the final output.
         magick_image.format(format)
         original_density = magick_image.resolution
-        scale_factor = original_density[0].to_f / 4.166666 # No clue why the resolution needs to be reduced for
-        # the pdf otherwise the resulting image shrinks.
+        scale_factor = original_density[0].to_f / 4.166666 # Convert from default 300 DPI to 72.
         magick_image.format('pdf', 0, { density: scale_factor.to_s })
         Origami::PDF.read(StringIO.new(magick_image.to_blob))
       end
 
       # Extracts multiple images from a given local input source.
       #
-      # @param [Mindee::Input::Source::LocalInputSource] input_source
+      # @param [Input::Source::LocalInputSource] input_source
       # @param [Integer] page_id ID of the Page to extract from.
-      # @param [Array<Array<Mindee::Geometry::Point>>, Array<Mindee::Geometry::Quadrangle>] polygons List of coordinates
-      # to extract.
-      # @return [Array<Mindee::Image::ExtractedImage>] Extracted Images.
+      # @param [Array<Array<Geometry::Point>>, Array<Geometry::Quadrilateral>] polygons List of coordinates to extract.
+      # @return [Array<Image::ExtractedImage>] Extracted Images.
       def self.extract_multiple_images_from_source(input_source, page_id, polygons)
         new_stream = load_input_source_pdf_page_as_stringio(input_source, page_id)
         new_stream.seek(0)
@@ -44,11 +41,11 @@ module Mindee
 
       # Extracts images from their positions on a file (as polygons).
       #
-      # @param [Mindee::Input::Source::LocalInputSource] input_source Local input source.
+      # @param [Input::Source::LocalInputSource] input_source Local input source.
       # @param [StringIO] pdf_stream Buffer of the PDF.
       # @param [Integer] page_id Page ID.
-      # @param [Array<Mindee::Geometry::Point, Mindee::Geometry::Polygon, Mindee::Geometry::Quadrangle>] polygons
-      # @return [Array<Mindee::Image::ExtractedImage>] Extracted Images.
+      # @param [Array<Geometry::Point, Geometry::Polygon, Geometry::Quadrilateral>] polygons
+      # @return [Array<Image::ExtractedImage>] Extracted Images.
       def self.extract_images_from_polygons(input_source, pdf_stream, page_id, polygons)
         extracted_elements = []
 
@@ -90,12 +87,12 @@ module Mindee
       #
       # @param [StringIO] buffer Buffer containing the image.
       # @param [String] file_name Name for the file.
-      # @param [Object] page_id ID of the page the file was universal from.
-      # @param [Object] element_id ID of the element of a given page.
+      # @param [Integer] page_id ID of the page the file was universal from.
+      # @param [Integer] element_id ID of the element of a given page.
       def self.create_extracted_image(buffer, file_name, page_id, element_id)
         buffer.rewind
         ExtractedImage.new(
-          Mindee::Input::Source::BytesInputSource.new(buffer.read.to_s, file_name),
+          Input::Source::BytesInputSource.new(buffer.read.to_s, file_name),
           page_id,
           element_id
         )
@@ -109,7 +106,7 @@ module Mindee
       def self.load_input_source_pdf_page_as_stringio(input_file, page_id)
         input_file.io_stream.rewind
         if input_file.pdf?
-          Mindee::PDF::PDFProcessor.get_page(Origami::PDF.read(input_file.io_stream), page_id)
+          PDF::PDFProcessor.get_page(Origami::PDF.read(input_file.io_stream), page_id)
         else
           input_file.io_stream
         end

data/lib/mindee/input/inference_parameters.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Input
+    # Parameters to set when sending a file for inference.
+    class InferenceParameters
+      # @return [String] ID of the model (required).
+      attr_reader :model_id
+
+      # @return [Boolean, nil] Enable Retrieval-Augmented Generation.
+      attr_reader :rag
+
+      # @return [String, nil] Optional alias for the file.
+      attr_reader :file_alias
+
+      # @return [Array<String>, nil] Optional list of Webhooks IDs to propagate the API response to.
+      attr_reader :webhook_ids
+
+      # @return [PollingOptions] Options for polling. Set only if having timeout issues.
+      attr_reader :polling_options
+
+      # @return [Boolean, nil] Whether to close the file after parsing.
+      attr_reader :close_file
+
+      # @param [String] model_id ID of the model
+      # @param [FalseClass] rag Whether to enable rag.
+      # @param [nil] file_alias File alias, if applicable.
+      # @param [nil] webhook_ids
+      # @param [nil] polling_options
+      # @param [TrueClass] close_file
+      def initialize(model_id, rag: false, file_alias: nil, webhook_ids: nil, polling_options: nil, close_file: true)
+        raise Errors::MindeeInputError, 'Model ID is required.' if model_id.empty? || model_id.nil?
+
+        @model_id = model_id
+        @rag = rag || false
+        @file_alias = file_alias
+        @webhook_ids = webhook_ids || []
+        @polling_options = get_clean_polling_options(polling_options)
+        @close_file = close_file.nil? || close_file
+      end
+
+      # Validates the parameters for async auto-polling
+      def validate_async_params
+        min_delay_sec = 1
+        min_initial_delay_sec = 1
+        min_retries = 2
+
+        if @polling_options.delay_sec < min_delay_sec
+          raise ArgumentError,
+                "Cannot set auto-poll delay to less than #{min_delay_sec} second(s)"
+        end
+        if @polling_options.initial_delay_sec < min_initial_delay_sec
+          raise ArgumentError,
+                "Cannot set initial parsing delay to less than #{min_initial_delay_sec} second(s)"
+        end
+        return unless @polling_options.max_retries < min_retries
+
+        raise ArgumentError,
+              "Cannot set auto-poll retries to less than #{min_retries}"
+      end
+
+      # Loads a prediction from a Hash.
+      # @param [Hash] params Parameters to provide as a hash.
+      # @return [InferenceParameters]
+      def self.from_hash(params: {})
+        params.transform_keys!(&:to_sym)
+
+        if params.empty? || params[:model_id].nil? || params[:model_id].empty?
+          raise Errors::MindeeInputError, 'Model ID is required.'
+        end
+
+        model_id = params.fetch(:model_id)
+        rag = params.fetch(:rag, false)
+        file_alias = params.fetch(:file_alias, nil)
+        webhook_ids = params.fetch(:webhook_ids, [])
+        polling_options_input = params.fetch(:page_options, PollingOptions.new)
+        if polling_options_input.is_a?(Hash)
+          polling_options_input = polling_options_input.transform_keys(&:to_sym)
+          PollingOptions.new(
+            initial_delay_sec: polling_options_input.fetch(:initial_delay_sec, 2.0),
+            delay_sec: polling_options_input.fetch(:delay_sec, 1.5),
+            max_retries: polling_options_input.fetch(:max_retries, 80)
+          )
+        end
+        close_file = params.fetch(:close_file, true)
+        InferenceParameters.new(model_id, rag: rag, file_alias: file_alias, webhook_ids: webhook_ids,
+                                          close_file: close_file)
+      end
+
+      private
+
+      # Cleans a proper polling options object potentially from a hash.
+      # @param [Hash, PollingOptions, nil] polling_options Polling options.
+      # @return [PollingOptions] Valid polling options object.
+      def get_clean_polling_options(polling_options)
+        return PollingOptions.new if polling_options.is_a?(PollingOptions)
+
+        if polling_options.is_a?(Hash)
+          polling_options = polling_options.transform_keys(&:to_sym)
+          output_polling_options = PollingOptions.new(
+            initial_delay_sec: polling_options.fetch(:initial_delay_sec, 2.0),
+            delay_sec: polling_options.fetch(:delay_sec, 1.5),
+            max_retries: polling_options.fetch(:max_retries, 80)
+          )
+        else
+          output_polling_options = if polling_options.is_a?(PollingOptions)
+                                     polling_options || PollingOptions.new
+                                   else
+                                     PollingOptions.new
+                                   end
+        end
+        output_polling_options
+      end
+    end
+  end
+end

data/lib/mindee/input/local_response.rb

@@ -62,11 +62,20 @@ module Mindee
       end
 
       # @param secret_key [String] Secret key, either a string or a byte/byte array.
-      # @param signature [String]
+      # @param signature [String] Signature to match
       # @return [bool]
       def valid_hmac_signature?(secret_key, signature)
         signature == get_hmac_signature(secret_key)
       end
+
+      # Deserializes a loaded response
+      # @param response_class [Parsing::V2::CommonResponse] class to return.
+      # @return [Parsing::V2::JobResponse, Parsing::V2::InferenceResponse]
+      def deserialize_response(response_class)
+        response_class.new(as_hash) # : Parsing::V2::JobResponse | Parsing::V2::InferenceResponse
+      rescue StandardError
+        raise Errors::MindeeInputError, 'Invalid response provided.'
+      end
     end
   end
 end

data/lib/mindee/input/polling_options.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Input
+    # Options for asynchronous polling.
+    class PollingOptions
+      # @return [Integer, Float] Initial delay before the first polling attempt (in seconds).
+      attr_reader :initial_delay_sec
+
+      # @return [Integer, Float] Delay between each polling attempt (in seconds).
+      attr_reader :delay_sec
+
+      # @return [Integer] Total number of polling attempts.
+      attr_reader :max_retries
+
+      # @param initial_delay_sec [Float] Initial delay before the first attempt (default:2.0).
+      # @param delay_sec [Float] Delay between attempts (default: 1.5).
+      # @param max_retries [Integer] Maximum number of retries (default:80).
+      def initialize(initial_delay_sec: 2.0, delay_sec: 1.5, max_retries: 80)
+        @initial_delay_sec = initial_delay_sec
+        @delay_sec = delay_sec
+        @max_retries = max_retries
+      end
+    end
+  end
+end

data/lib/mindee/input/sources/base64_input_source.rb

@@ -18,12 +18,12 @@ module Mindee
 
         # Overload of the same function to prevent a base64 from being re-encoded.
         # @param close [bool]
-        # @return [Array<String, [String, aBinaryString ], [Hash, nil] >]
+        # @return [Array<[String, aBinaryString ], [Hash, nil] >]
         def read_contents(close: true)
           @io_stream.seek(0)
           data = @io_stream.read
           @io_stream.close if close
-          ['document', [data].pack('m'), { filename: Source.convert_to_unicode_escape(@filename) }]
+          [[data].pack('m'), { filename: Source.convert_to_unicode_escape(@filename) }]
         end
       end
     end