mindee 3.17.0 → 3.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12e0bc8339961d2e6be4c5dfdc9537d34ab63f449c435275324b95c031299764
-  data.tar.gz: 24021ef9d0175075365efc9e056d67f3d553b1ad7b95a5a2876d29fcff15031c
+  metadata.gz: ef56483dc0576b931b3d88b57e4512abd44ea4e216ed29dc1097ada3fa5b00fb
+  data.tar.gz: 8d4f6c2b99c113439b2332244cd89619189704bc75655121c26ba0122118d539
 SHA512:
-  metadata.gz: df5dc07d28d67b0e1fe1c64c3123aeb3f9c8926264aed396fdd64858f8b06d6d2485745c61d15c35e0ae3f92ee6773eaacbdc86ba3256cefd7349fb0ff90533a
-  data.tar.gz: e07e7b776f21398ce3a9197fb54afef57361ffda29c198564da9ffa1fa0eea85830c7d1601177c241219bea60c61cbb9cbcec66ad0c80d55ffcc7aab0e8cfe4f
+  metadata.gz: a0461aea7ba2804e36ddc833e1ec24888227484d1ad1f1471b8b8859cfaffc14a94f623672b749fe0f73584c6c215f26d87f2e11cbeb701fc8cc9cf86088ec6f
+  data.tar.gz: aed38431cddde8abc620cf4701ecf7299929a0216b0a9e717d7ef56732211fb38ae12d093fca8839cbd981c43047f0a87088587c44fc7f4c9ff9f4ae56438f7d

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Mindee Ruby API Library Changelog
 
+## v3.19.0 - 2025-01-14
+### Changes
+* :sparkles: add support for US Mail V3
+* :recycle: increase async retry timers
+
+
+## v3.18.0 - 2024-12-13
+### Changes
+* :sparkles: allow local downloading of remote sources
+* :coffin: remove support for (FR) Carte Vitale V1 in favor of French Health Card V1
+### Fixes
+* :bug: fix tax-extraction script
+
+
 ## v3.17.0 - 2024-11-28
 ### Changes
 * :sparkles: add support for workflows

data/README.md

@@ -116,7 +116,7 @@ result = mindee_client.parse(
 puts result.document
 ```
 
-### Custom Document (API Builder)
+### Custom Documents (docTI & Custom APIs)
 
 ```ruby
 require 'mindee'
@@ -131,9 +131,9 @@ endpoint = mindee_client.create_endpoint(
 # Load a file from disk
 input_source = mindee_client.source_from_path('/path/to/the/file.ext')
 
-result = mindee_client.parse(
+result = mindee_client.enqueue_and_parse(
   input_source,
-  Mindee::Product::Custom::CustomV1,
+  Mindee::Product::Generated::GeneratedV1,
   endpoint: endpoint
 )
 
@@ -181,7 +181,7 @@ customize the experience.
 * [EU Driver License OCR Ruby](https://developers.mindee.com/docs/ruby-eu-driver-license-ocr)
 * [FR Bank Account Details OCR Ruby](https://developers.mindee.com/docs/ruby-fr-bank-account-details-ocr)
 * [FR Bank Statement OCR Ruby](https://developers.mindee.com/docs/ruby-fr-bank-statement-ocr)
-* [FR Carte Vitale OCR Ruby](https://developers.mindee.com/docs/ruby-fr-carte-vitale-ocr)
+* [FR Health Card OCR Ruby](https://developers.mindee.com/docs/ruby-fr-health-card-ocr)
 * [FR ID Card OCR Ruby](https://developers.mindee.com/docs/ruby-fr-carte-nationale-didentite-ocr)
 * [US Bank Check OCR Ruby](https://developers.mindee.com/docs/ruby-us-bank-check-ocr)
 * [US Driver License OCR Ruby](https://developers.mindee.com/docs/ruby-us-driver-license-ocr)

data/bin/mindee.rb

@@ -97,12 +97,6 @@ DOCUMENTS = {
     sync: false,
     async: true,
   },
-  "fr-carte-vitale" => {
-    description: "FR Carte Vitale",
-    doc_class: Mindee::Product::FR::CarteVitale::CarteVitaleV1,
-    sync: true,
-    async: false,
-  },
   "fr-id-card" => {
     description: "FR ID Card",
     doc_class: Mindee::Product::FR::IdCard::IdCardV2,

data/docs/code_samples/{carte_vitale_v1.txt → us_mail_v3_async.txt}

@@ -7,9 +7,9 @@ mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 input_source = mindee_client.source_from_path('/path/to/the/file.ext')
 
 # Parse the file
-result = mindee_client.parse(
+result = mindee_client.enqueue_and_parse(
   input_source,
-  Mindee::Product::FR::CarteVitale::CarteVitaleV1
+  Mindee::Product::US::UsMail::UsMailV3
 )
 
 # Print a full summary of the parsed data in RST format

data/docs/custom_v1.md

@@ -4,7 +4,7 @@ category: 622b805aaec68102ea7fcbc2
 slug: ruby-api-builder-ocr
 parentDoc: 6294d97ee723f1008d2ab28e
 ---
-> 🚧 This product is still supported, but is considered to be deprecated. If you are looking for the DocTI API documentation, you can find it [here](https://developers.mindee.com/docs/ruby-generated-ocr).
+> 🚧 This product is still supported, but is considered to be deprecated. If you are looking for the docTI API documentation, you can find it [here](https://developers.mindee.com/docs/ruby-generated-ocr).
 
 # Quick-Start
 

data/docs/getting_started.md

@@ -226,20 +226,20 @@ result = mindee_client.parse(
 )
 ```
 
-### Custom Documents
+### Custom Documents (docTI)
 For custom documents, the endpoint to use must also be set, and it must take in an `endpoint_name`:
 
 ```ruby
-endpoint = mindee_client.create_endpoint(endpoint_name: 'wnine')
+endpoint = mindee_client.create_endpoint(endpoint_name: 'wnine', account_name: 'my-account')
 
-result = mindee_client.parse(
+result = mindee_client.enqueue_and_parse(
   input_source,
-  Mindee::Product::Custom::CustomV1,
+  Mindee::Product::Generated::GeneratedV1,
   endpoint: endpoint
 )
 ```
 
-This is because the `CustomV1` class is enough to handle the return processing, but the actual endpoint needs to be specified.
+This is because the `GeneratedV1` class is enough to handle the return processing, but the actual endpoint needs to be specified.
 
 ## Process the Result
 The response object is common to all documents, including custom documents. The main properties are:

data/docs/{us_mail_v2.md → us_mail_v3.md}

@@ -22,7 +22,7 @@ input_source = mindee_client.source_from_path('/path/to/the/file.ext')
 # Parse the file
 result = mindee_client.enqueue_and_parse(
   input_source,
-  Mindee::Product::US::UsMail::UsMailV2
+  Mindee::Product::US::UsMail::UsMailV3
 )
 
 # Print a full summary of the parsed data in RST format
@@ -35,7 +35,20 @@ puts result.document
 
 **Output (RST):**
 ```rst
-:Sender Name: zed
+########
+Document
+########
+:Mindee ID: f9c36f59-977d-4ddc-9f2d-31c294c456ac
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/us_mail v3.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Sender Name: company zed
 :Sender Address:
   :City: Dallas
   :Complete Address: 54321 Elm Street, Dallas, Texas 54321
@@ -44,11 +57,12 @@ puts result.document
   :Street: 54321 Elm Street
 :Recipient Names: Jane Doe
 :Recipient Addresses:
-  +-----------------+-------------------------------------+-------------------+-------------+------------------------+-------+---------------------------+
-  | City            | Complete Address                    | Is Address Change | Postal Code | Private Mailbox Number | State | Street                    |
-  +=================+=====================================+===================+=============+========================+=======+===========================+
-  | Detroit         | 1234 Market Street PMB 4321, Det... |                   | 12345       | 4321                   | MI    | 1234 Market Street        |
-  +-----------------+-------------------------------------+-------------------+-------------+------------------------+-------+---------------------------+
+  +-----------------+-------------------------------------+-------------------+-------------+------------------------+-------+---------------------------+-----------------+
+  | City            | Complete Address                    | Is Address Change | Postal Code | Private Mailbox Number | State | Street                    | Unit            |
+  +=================+=====================================+===================+=============+========================+=======+===========================+=================+
+  | Detroit         | 1234 Market Street PMB 4321, Det... | False             | 12345       | 4321                   | MI    | 1234 Market Street        |                 |
+  +-----------------+-------------------------------------+-------------------+-------------+------------------------+-------+---------------------------+-----------------+
+:Return to Sender: False
 ```
 
 # Field Types
@@ -78,7 +92,7 @@ Fields which are specific to this product; they are not used in any other produc
 ### Recipient Addresses Field
 The addresses of the recipients.
 
-A `UsMailV2RecipientAddress` implements the following attributes:
+A `UsMailV3RecipientAddress` implements the following attributes:
 
 * `city` (String): The city of the recipient's address.
 * `complete` (String): The complete address of the recipient.
@@ -87,12 +101,13 @@ A `UsMailV2RecipientAddress` implements the following attributes:
 * `private_mailbox_number` (String): The private mailbox number of the recipient's address.
 * `state` (String): Second part of the ISO 3166-2 code, consisting of two letters indicating the US State.
 * `street` (String): The street of the recipient's address.
+* `unit` (String): The unit number of the recipient's address.
 Fields which are specific to this product; they are not used in any other product.
 
 ### Sender Address Field
 The address of the sender.
 
-A `UsMailV2SenderAddress` implements the following attributes:
+A `UsMailV3SenderAddress` implements the following attributes:
 
 * `city` (String): The city of the sender's address.
 * `complete` (String): The complete address of the sender.
@@ -101,10 +116,17 @@ A `UsMailV2SenderAddress` implements the following attributes:
 * `street` (String): The street of the sender's address.
 
 # Attributes
-The following fields are extracted for US Mail V2:
+The following fields are extracted for US Mail V3:
+
+## Return to Sender
+**is_return_to_sender** ([BooleanField](#boolean-field)): Whether the mailing is marked as return to sender.
+
+```rb
+puts result.document.inference.prediction.is_return_to_sender.value
+```
 
 ## Recipient Addresses
-**recipient_addresses** (Array<[UsMailV2RecipientAddress](#recipient-addresses-field)>): The addresses of the recipients.
+**recipient_addresses** (Array<[UsMailV3RecipientAddress](#recipient-addresses-field)>): The addresses of the recipients.
 
 ```rb
 for recipient_addresses_elem in result.document.inference.prediction.recipient_addresses do
@@ -122,7 +144,7 @@ end
 ```
 
 ## Sender Address
-**sender_address** ([UsMailV2SenderAddress](#sender-address-field)): The address of the sender.
+**sender_address** ([UsMailV3SenderAddress](#sender-address-field)): The address of the sender.
 
 ```rb
 puts result.document.inference.prediction.sender_address.value

data/lib/mindee/client.rb

@@ -151,7 +151,7 @@ module Mindee
     #  This performs a cropping operation on the server and will increase response time.
     # @param initial_delay_sec [Integer, Float] initial delay before polling. Defaults to 2.
     # @param delay_sec [Integer, Float] delay between polling attempts. Defaults to 1.5.
-    # @param max_retries [Integer] maximum amount of retries. Defaults to 60.
+    # @param max_retries [Integer] maximum amount of retries. Defaults to 80.
     # @return [Mindee::Parsing::Common::ApiResponse]
     def enqueue_and_parse(
       input_source,
@@ -164,7 +164,7 @@ module Mindee
       cropper: false,
       initial_delay_sec: 2,
       delay_sec: 1.5,
-      max_retries: 60
+      max_retries: 80
     )
       enqueue_res = enqueue(
         input_source,

data/lib/mindee/extraction/tax_extractor/tax_extractor.rb

@@ -2,6 +2,8 @@
 
 require_relative 'ocr_extractor'
 
+# rubocop:disable Metrics/ClassLength
+
 module Mindee
   module Extraction
     # Tax extractor class
@@ -72,9 +74,12 @@ module Mindee
         reconstructed_hash['code'] =
           found_hash['code'].nil? ? found_hash['code'] : found_hash['code'].sub(%r{\s*\.*\s*$}, '')
 
-        if found_hash['rate'] && found_hash['rate'] < 1 && (found_hash['rate']).positive?
-          found_hash['rate'] =
-            found_hash['rate'] * 100
+        if found_hash['rate']
+          if found_hash['rate'].abs < 1
+            found_hash['rate'] *= 10
+          elsif found_hash['rate'].abs > 100
+            found_hash['rate'] /= 10
+          end
         end
         found_hash = swap_rates_if_needed(found_hash, min_rate_percentage, max_rate_percentage)
         found_hash = decimate_rates_if_needed(found_hash)
@@ -125,18 +130,28 @@ module Mindee
       # @param found_hash [Hash] Hash of currently retrieved values
       # @return [Hash]
       def self.set_base_and_value(reconstructed_hash, found_hash)
-        if found_hash['base'].nil?
-          reconstructed_hash['base'] = found_hash['base']
-          reconstructed_hash['value'] = found_hash['value']
-        elsif found_hash['value'].nil? && found_hash['base'] < found_hash['value']
-          reconstructed_hash['base'] = found_hash['value']
-          reconstructed_hash['value'] = found_hash['base']
-        else
-          reconstructed_hash['value'] = found_hash['value']
+        base = found_hash['base']
+        value = found_hash['value']
+
+        if base && value
+          reconstructed_hash['base'], reconstructed_hash['value'] = [base, value].minmax
+        elsif base
+          reconstructed_hash['base'] = base
+        elsif value
+          reconstructed_hash['value'] = value
+          calculate_base(reconstructed_hash)
         end
+
         reconstructed_hash
       end
 
+      def self.calculate_base(hash)
+        rate = hash['rate']
+        return unless rate&.positive?
+
+        hash['base'] = hash['value'] / (rate / 100.0)
+      end
+
       # Extracts a single custom type of tax.
       # For the sake of simplicity, this only extracts the first example, unless specifically instructed otherwise.
       # @param ocr_result [Mindee::Parsing::Common::Ocr::Ocr] result of the OCR.
@@ -149,7 +164,6 @@ module Mindee
 
         tax_names.sort!
         found_hash = pick_best(extract_horizontal_tax(ocr_result, tax_names), tax_names)
-        # a tax is considered found horizontally if it has a value, otherwise it is vertical
         if found_hash.nil? || found_hash['value'].nil?
           found_hash = extract_vertical_tax(ocr_result, tax_names,
                                             found_hash)
@@ -240,14 +254,14 @@ module Mindee
         linear_pattern_percent_first = %r{
           ((?:\s*-\s*)?(?:\d*[.,])*\d+[ ]?%?|%?[ ]?(?:\s*-\s*)?(?:\d*[.,])*\d+)?[ .]?
           ([a-zA-ZÀ-ÖØ-öø-ÿ .]*[a-zA-ZÀ-ÖØ-öø-ÿ]?)[ .]?
-          ((?:\s*-\s*)?(?:\d*[.,])+\d{2,})?[ .]*
-          ((?:\s*-\s*)?(\d*[.,])*\d{2,})?
+          ((?:\s*-\s*)?(?:\d*[.,])+\d+)?[ .]*
+          ((?:\s*-\s*)?(\d*[.,])*\d+)?
         }x
         linear_pattern_percent_second = %r{
           ([a-zA-ZÀ-ÖØ-öø-ÿ .]*[a-zA-ZÀ-ÖØ-öø-ÿ]?)[ .]*
           ((?:\s*-\s*)?(?:\d*[.,])*\d+[ ]?%?|%?[ ]?(?:\s*-\s*)?(?:\d*[.,])*\d+)?[ .]?
-          ((?:\s*-\s*)?(?:\d*[.,])+\d{2,})?[ .]*
-          ((?:\s*-\s*)?(\d*[.,])*\d{2,})?
+          ((?:\s*-\s*)?(?:\d*[.,])+\d+)?[ .]*
+          ((?:\s*-\s*)?(\d*[.,])*\d+)?
         }x
         ocr_result.mvision_v1.pages.each.with_index do |page, page_id|
           page.all_lines.each do |line|
@@ -304,7 +318,7 @@ module Mindee
           page.all_words.each do |word|
             next if match_index(word.text, tax_names).nil?
 
-            reconstructed_line = ocr_result.reconstruct_vertically(word.polygon, page_id)
+            reconstructed_line = ocr_result.reconstruct_vertically(word.polygon, page_id, 0.25)
             found_hash['page_id'] = page_id if found_hash['page_id'].nil?
             found_hash['code'] = word.text.strip if found_hash['code'].nil?
             found_hash = extract_vertical_tax_values(reconstructed_line, found_hash)
@@ -316,8 +330,9 @@ module Mindee
       private_class_method :extract_percentage_from_tax, :extract_basis_and_value, :extract_tax_from_horizontal_line,
                            :extract_horizontal_tax, :extract_vertical_tax_values, :extract_vertical_tax,
                            :create_tax_field, :fix_rate, :pick_best, :calculate_score, :curate_values,
-                           :decimate_rates_if_needed, :extract_basis_and_value, :set_base_and_value, :valid_candidate?,
-                           :swap_rates_if_needed
+                           :decimate_rates_if_needed, :set_base_and_value, :valid_candidate?,
+                           :swap_rates_if_needed, :calculate_base
     end
   end
 end
+# rubocop:enable Metrics/ClassLength

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Mindee
+  module Input
+    module Source
+      # Load a document from a base64 string.
+      class Base64InputSource < LocalInputSource
+        # @param base64_string [String]
+        # @param filename [String]
+        # @param fix_pdf [Boolean]
+        def initialize(base64_string, filename, fix_pdf: false)
+          io_stream = StringIO.new(base64_string.unpack1('m*'))
+          io_stream.set_encoding Encoding::BINARY
+          super(io_stream, filename, fix_pdf: fix_pdf)
+        end
+
+        # Overload of the same function to prevent a base64 from being re-encoded.
+        # @param close [Boolean]
+        # @return [Array<String, [String, aBinaryString ], [Hash, nil] >]
+        def read_document(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) }]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Mindee
+  module Input
+    module Source
+      # Load a document from raw bytes.
+      class BytesInputSource < LocalInputSource
+        # @param raw_bytes [String]
+        # @param filename [String]
+        # @param fix_pdf [Boolean]
+        def initialize(raw_bytes, filename, fix_pdf: false)
+          io_stream = StringIO.new(raw_bytes)
+          io_stream.set_encoding Encoding::BINARY
+          super(io_stream, filename, fix_pdf: fix_pdf)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Mindee
+  module Input
+    module Source
+      # Load a document from a file handle.
+      class FileInputSource < LocalInputSource
+        # @param input_file [File]
+        # @param filename [String]
+        # @param fix_pdf [Boolean]
+        def initialize(input_file, filename, fix_pdf: false)
+          io_stream = input_file
+          super(io_stream, filename, fix_pdf: fix_pdf)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require 'marcel'
+
+require_relative '../../pdf'
+require_relative '../../image'
+
+module Mindee
+  module Input
+    # Document source handling.
+    module Source
+      # Mime types accepted by the server.
+      ALLOWED_MIME_TYPES = [
+        'application/pdf',
+        'image/heic',
+        'image/png',
+        'image/jpeg',
+        'image/tiff',
+        'image/webp',
+      ].freeze
+
+      # Standard error for invalid mime types
+      class MimeTypeError < StandardError
+      end
+
+      # Error sent if the file's mimetype isn't allowed
+      class InvalidMimeTypeError < MimeTypeError
+        # @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 #{ALLOWED_MIME_TYPES.join(', ')}")
+        end
+      end
+
+      # Error sent if a pdf file couldn't be fixed
+      class UnfixablePDFError < MimeTypeError
+        def initialize
+          super("Corrupted PDF couldn't be repaired.")
+        end
+      end
+
+      # Base class for loading documents.
+      class LocalInputSource
+        # @return [String]
+        attr_reader :filename
+        # @return [String]
+        attr_reader :file_mimetype
+        # @return [StringIO]
+        attr_reader :io_stream
+
+        # @param io_stream [StringIO]
+        # @param filename [String]
+        # @param fix_pdf [Boolean]
+        def initialize(io_stream, filename, fix_pdf: false)
+          @io_stream = io_stream
+          @filename = filename
+          @file_mimetype = if fix_pdf
+                             Marcel::MimeType.for @io_stream
+                           else
+                             Marcel::MimeType.for @io_stream, name: @filename
+                           end
+          return if ALLOWED_MIME_TYPES.include? @file_mimetype
+
+          if filename.end_with?('.pdf') && fix_pdf
+            rescue_broken_pdf(@io_stream)
+            @file_mimetype = Marcel::MimeType.for @io_stream
+
+            return if ALLOWED_MIME_TYPES.include? @file_mimetype
+          end
+
+          raise InvalidMimeTypeError, @file_mimetype.to_s
+        end
+
+        # 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]
+        def rescue_broken_pdf(stream)
+          stream.gets('%PDF-')
+          raise UnfixablePDFError if stream.eof? || stream.pos > 500
+
+          stream.pos = stream.pos - 5
+          data = stream.read
+          @io_stream.close
+
+          @io_stream = StringIO.new
+          @io_stream << data
+        end
+
+        # Shorthand for pdf mimetype validation.
+        def pdf?
+          @file_mimetype.to_s == 'application/pdf'
+        end
+
+        # Parses a PDF file according to provided options.
+        # @param options [Hash, nil] Page cutting/merge options:
+        #
+        #  * `:page_indexes` Zero-based list of page indexes.
+        #  * `:operation` Operation to apply on the document, given the `page_indexes specified:
+        #      * `: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)
+          @io_stream.seek(0)
+          @io_stream = PdfProcessor.parse(@io_stream, options)
+        end
+
+        # Reads a document.
+        # @param close [Boolean]
+        # @return [Array<String, [String, aBinaryString ], [Hash, nil] >]
+        def read_document(close: true)
+          @io_stream.seek(0)
+          # Avoids needlessly re-packing some files
+          data = @io_stream.read
+          @io_stream.close if close
+          ['document', data, { filename: Mindee::Input::Source.convert_to_unicode_escape(@filename) }]
+        end
+
+        def count_pdf_pages
+          return 1 unless pdf?
+
+          @io_stream.seek(0)
+          pdf_processor = Mindee::PDF::PdfProcessor.open_pdf(@io_stream)
+          pdf_processor.pages.size
+        end
+
+        # Compresses the file, according to the provided info.
+        # @param [Integer] quality Quality of the output file.
+        # @param [Integer, nil] max_width Maximum width (Ignored for PDFs).
+        # @param [Integer, nil] max_height Maximum height (Ignored for PDFs).
+        # @param [Boolean] force_source_text Whether to force the operation on PDFs with source text.
+        #   This will attempt to re-render PDF text over the rasterized original. If disabled, ignored the operation.
+        #   WARNING: this operation is strongly discouraged.
+        # @param [Boolean] disable_source_text If the PDF has source text, whether to re-apply it to the original or
+        #   not. Needs force_source_text to work.
+        def compress!(quality: 85, max_width: nil, max_height: nil, force_source_text: false, disable_source_text: true)
+          buffer = if pdf?
+                     Mindee::PDF::PDFCompressor.compress_pdf(
+                       @io_stream,
+                       quality: quality,
+                       force_source_text_compression: force_source_text,
+                       disable_source_text: disable_source_text
+                     )
+                   else
+                     Mindee::Image::ImageCompressor.compress_image(
+                       @io_stream,
+                       quality: quality,
+                       max_width: max_width,
+                       max_height: max_height
+                     )
+                   end
+          @io_stream = buffer
+          @io_stream.rewind
+        end
+
+        # Checks whether the file has source text if it is a pdf. False otherwise
+        # @return [Boolean] True if the file is a PDF and has source text.
+        def source_text?
+          Mindee::PDF::PDFTools.source_text?(@io_stream)
+        end
+      end
+
+      # Replaces non-ASCII characters by their UNICODE escape sequence.
+      # Keeps other characters as is.
+      # @return A clean String.
+      def self.convert_to_unicode_escape(string)
+        unicode_escape_string = ''.dup
+        string.each_char do |char|
+          unicode_escape_string << if char.bytesize > 1
+                                     "\\u#{char.unpack1('U').to_s(16).rjust(4, '0')}"
+                                   else
+                                     char
+                                   end
+        end
+        unicode_escape_string
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Mindee
+  module Input
+    # Document source handling.
+    module Source
+      # Load a document from a path.
+      class PathInputSource < LocalInputSource
+        # @param filepath [String]
+        # @param fix_pdf [Boolean]
+        def initialize(filepath, fix_pdf: false)
+          io_stream = File.open(filepath, 'rb')
+          super(io_stream, File.basename(filepath), fix_pdf: fix_pdf)
+        end
+      end
+    end
+  end
+end