mindee 4.6.0 → 4.7.0.pre.rc1

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

@@ -30,11 +30,11 @@ module Mindee
 
       # 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
+      # @param [Array<Array<Geometry::Point>>, Array<Geometry::Quadrilateral>] polygons List of coordinates.
       # to extract.
-      # @return [Array<Mindee::Image::ExtractedImage>] Extracted Images.
+      # @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 +44,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 +90,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 +109,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::JobResponse, Parsing::V2::InferenceResponse] class to return.
+      # @return [Parsing::V2::JobResponse, Parsing::V2::InferenceResponse]
+      def deserialize_response(response_class)
+        response_class.new(as_hash)
+      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

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

@@ -27,7 +27,7 @@ module Mindee
         attr_reader :filename
         # @return [String]
         attr_reader :file_mimetype
-        # @return [StringIO]
+        # @return [StringIO | File]
         attr_reader :io_stream
 
         # @param io_stream [StringIO, File]
@@ -60,7 +60,7 @@ module Mindee
         # Attempts to fix pdf files if mimetype is rejected.
         # "Broken PDFs" are often a result of third-party injecting invalid headers.
         # This attempts to remove them and send the file
-        # @param stream [StringIO]
+        # @param stream [StringIO, File]
         def rescue_broken_pdf(stream)
           stream.gets('%PDF-')
           raise Errors::MindeePDFError if stream.eof? || stream.pos > 500
@@ -78,7 +78,7 @@ module Mindee
           @file_mimetype.to_s == 'application/pdf'
         end
 
-        # Parses a PDF file according to provided options.
+        # Cuts a PDF file according to provided options.
         # @param options [PageOptions, nil] Page cutting/merge options:
         #
         #  * `:page_indexes` Zero-based list of page indexes.
@@ -86,14 +86,20 @@ module Mindee
         #      * `:KEEP_ONLY` - keep only the specified pages, and remove all others.
         #      * `:REMOVE` - remove the specified pages, and keep all others.
         #  * `:on_min_pages` Apply the operation only if document has at least this many pages.
-        def process_pdf(options)
+        def apply_page_options(options)
           @io_stream.seek(0)
           @io_stream = PDF::PDFProcessor.parse(@io_stream, options)
         end
 
+        # @deprecated Use {#apply_page_options} instead.
+        # @see #apply_page_options
+        def process_pdf(options)
+          apply_page_options(options)
+        end
+
         # Reads a document.
         # @param close [bool]
-        # @return [Array<String, [String, aBinaryString ], [Hash, nil] >]
+        # @return [Array<>]
         def read_contents(close: true)
           logger.debug("Reading data from: #{@filename}")
           @io_stream.seek(0)
@@ -101,20 +107,21 @@ module Mindee
           data = @io_stream.read
           @io_stream.rewind
           @io_stream.close if close
-          ['document', data, { filename: Mindee::Input::Source.convert_to_unicode_escape(@filename) }]
+          [data, { filename: Mindee::Input::Source.convert_to_unicode_escape(@filename) }]
         end
 
         # Write the file to a given path. Uses the initial file name by default.
         # @param path [String] Path to write the file to.
         def write_to_file(path)
-          full_path = if File.directory?(path) || path.end_with?('/')
-                        File.join(path, @filename)
-                      else
-                        path
-                      end
+          t_path = if File.directory?(path || '') || path.to_s.end_with?('/')
+                     File.join(path || '', @filename)
+                   else
+                     path
+                   end
+          full_path = File.expand_path(t_path || '')
           FileUtils.mkdir_p(File.dirname(full_path))
           @io_stream.rewind
-          File.binwrite(full_path, @io_stream.read)
+          File.binwrite(full_path, @io_stream.read || '')
           logger.debug("Wrote file successfully to #{full_path}")
           @io_stream.rewind
         end

data/lib/mindee/input.rb

@@ -1,3 +1,5 @@
 # frozen_string_literal: true
 
+require_relative 'input/inference_parameters'
+require_relative 'input/polling_options'
 require_relative 'input/sources'

data/lib/mindee/page_options.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Class for page options in parse calls.
+  # @!attribute page_indexes [Array[Integer]] Zero-based list of page indexes.
+  # @!attribute operation [:KEEP_ONLY, :REMOVE] Operation to apply on the document, given the specified page indexes:
+  #   * `:KEEP_ONLY` - keep only the specified pages, and remove all others.
+  #   * `:REMOVE` - remove the specified pages, and keep all others.
+  # @!attribute on_min_pages [Integer, nil] Apply the operation only if the document has at least this many pages.
+  class PageOptions
+    attr_accessor :page_indexes, :operation, :on_min_pages
+
+    def initialize(params: {})
+      params ||= {}
+      params = params.transform_keys(&:to_sym)
+      @page_indexes = params.fetch(
+        :page_indexes,
+        [] # : Array[Integer]
+      )
+      @operation = params.fetch(:operation, :KEEP_ONLY)
+      @on_min_pages = params.fetch(:on_min_pages, nil)
+    end
+  end
+end