mindee 3.9.0 → 3.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a863bb97566add59f1d2385e9688cab9841a3c4b22228138dd72023ad0521fc
-  data.tar.gz: ff3097cb84eba1ceef71f229a1b6f0152ba2a5659b5b9955dae313046eacfc39
+  metadata.gz: cdf4542787e1ef24c74bf2104d3eacc5205afff3066ea24b0bea52b7d43d6993
+  data.tar.gz: 6d816b54bb34feb7d6c59db0f0a1f90cc34c5b6dd8155be315dfb698c88838d4
 SHA512:
-  metadata.gz: 26c78e63b0464261718d20718628d30df2f1b805c55e9d0d87670abfc4d97e7f0b0fdcab21c8e7810cffe0562923dde6a551fb59a8a8d393c535e89e7ed12d3c
-  data.tar.gz: dd333f2e4169061884be3bc39649862fab3fdcfc2bc9039f0b850cc2e5690194fa5915917dcaeb5d622b0df444bf8a8e81647ea9edc6b940c94324c37aefa7d6
+  metadata.gz: 3ee7621e86789bf3f3ff294d505d71272018f342936d05f74f17a57e7b15916f8cde1218ffe1fa7ff7e7d2331c2982562725994bbf3565290645b870756d113e
+  data.tar.gz: 9b48e7088ffcc75136714e10e0fca34975b6b94f0f8a5241fd775fbcde0e8a05a836ca9f8703a7dc1d00c2820717ccc0cc989c8c1ea390716a3119114347e111

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Mindee Ruby API Library Changelog
 
+## v3.11.0 - 2024-06-10
+### Changes
+* :sparkles: add custom tax extraction feature (#76)
+
+
+## v3.10.0 - 2024-05-31
+### Changes
+* :sparkles: add support for us mail v2 (#98)
+* :sparkles: add support for boolean fields
+* :sparkles: add support for webhooks (#97)
+### Fixes
+* :recycle: tweak display for LocaleField
+
+
 ## v3.9.0 - 2024-05-16
 ### Changes
 * :sparkles: update financial document to v1.7 & receipts to v5.2

data/docs/code_samples/us_mail_v2_async.txt

@@ -0,0 +1,19 @@
+require 'mindee'
+
+# Init a new client
+mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+
+# Load a file from disk
+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
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document
+
+# Print the document-level parsed data
+# puts result.document.inference.prediction

data/docs/us_mail_v2.md

@@ -0,0 +1,135 @@
+---
+title: US US Mail OCR Ruby
+---
+The Ruby OCR SDK supports the [US Mail API](https://platform.mindee.com/mindee/us_mail).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/us_mail/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![US Mail sample](https://github.com/mindee/client-lib-test-data/blob/main/products/us_mail/default_sample.jpg?raw=true)
+
+# Quick-Start
+```rb
+require 'mindee'
+
+# Init a new client
+mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+
+# Load a file from disk
+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
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document
+
+# Print the document-level parsed data
+# puts result.document.inference.prediction
+```
+
+**Output (RST):**
+```rst
+:Sender Name: zed
+:Sender Address:
+  :City: Dallas
+  :Complete Address: 54321 Elm Street, Dallas, Texas ...
+  :Postal Code: 54321
+  :State: TX
+  :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        |
+  +-----------------+-------------------------------------+-------------------+-------------+------------------------+-------+---------------------------+
+```
+
+# Field Types
+## Standard Fields
+These fields are generic and used in several products.
+
+### Basic Field
+Each prediction object contains a set of fields that inherit from the generic `Field` class.
+A typical `Field` object will have the following attributes:
+
+* **value** (`String`, `Float`, `Integer`, `Boolean`): corresponds to the field value. Can be `nil` if no value was extracted.
+* **confidence** (Float, nil): the confidence score of the field prediction.
+* **bounding_box** (`Mindee::Geometry::Quadrilateral`, `nil`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document.
+* **polygon** (`Mindee::Geometry::Polygon`, `nil`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image.
+* **page_id** (`Integer`, `nil`): the ID of the page, is `nil` when at document-level.
+* **reconstructed** (`Boolean`): indicates whether an object was reconstructed (not extracted as the API gave it).
+
+
+Aside from the previous attributes, all basic fields have access to a `to_s` method that can be used to print their value as a string.
+
+### String Field
+The text field `StringField` only has one constraint: it's **value** is a `String` (or `nil`).
+
+## Specific Fields
+Fields which are specific to this product; they are not used in any other product.
+
+### Recipient Addresses Field
+The addresses of the recipients.
+
+A `UsMailV2RecipientAddress` implements the following attributes:
+
+* `city` (String): The city of the recipient's address.
+* `complete` (String): The complete address of the recipient.
+* `is_address_change` (Boolean): Indicates if the recipient's address is a change of address.
+* `postal_code` (String): The postal code of the recipient's address.
+* `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.
+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:
+
+* `city` (String): The city of the sender's address.
+* `complete` (String): The complete address of the sender.
+* `postal_code` (String): The postal code of the sender'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 sender's address.
+
+# Attributes
+The following fields are extracted for US Mail V2:
+
+## Recipient Addresses
+**recipient_addresses** (Array<[UsMailV2RecipientAddress](#recipient-addresses-field)>): The addresses of the recipients.
+
+```rb
+for recipient_addresses_elem in result.document.inference.prediction.recipient_addresses do
+  puts recipient_addresses_elem.value
+end
+```
+
+## Recipient Names
+**recipient_names** (Array<[StringField](#string-field)>): The names of the recipients.
+
+```rb
+for recipient_names_elem in result.document.inference.prediction.recipient_names do
+  puts recipient_names_elem.value
+end
+```
+
+## Sender Address
+**sender_address** ([UsMailV2SenderAddress](#sender-address-field)): The address of the sender.
+
+```rb
+puts result.document.inference.prediction.sender_address.value
+```
+
+## Sender Name
+**sender_name** ([StringField](#string-field)): The name of the sender.
+
+```rb
+puts result.document.inference.prediction.sender_name.value
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/lib/mindee/client.rb

@@ -182,6 +182,17 @@ module Mindee
 
     # rubocop:enable Metrics/ParameterLists
 
+    # Load a prediction.
+    #
+    # @param product_class [Mindee::Product] class of the product
+    # @param local_response [Mindee::Input::LocalResponse]
+    # @return [Mindee::Parsing::Common::ApiResponse]
+    def load_prediction(product_class, local_response)
+      Mindee::Parsing::Common::ApiResponse.new(product_class, local_response.as_hash, local_response.as_hash.to_json)
+    rescue KeyError
+      raise 'No prediction found in local response.'
+    end
+
     # Load a document from an absolute path, as a string.
     # @param input_path [String] Path of file to open
     # @param fix_pdf [Boolean] Attempts to fix broken pdf if true

data/lib/mindee/extraction/ocr_extractor.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Extraction
+    # Generic extractor class
+    class OcrExtractor
+      # Checks for a list of possible matches in a string & returns the index of the first found candidate.
+      # Case & diacritics insensitive.
+      # @param text [String] string to search for matches.
+      # @param str_candidates [Array<String>] array of values to look for
+      # @return [Integer, nil]
+      def self.match_index(text, str_candidates)
+        idx = nil
+        str_candidates.each do |str_candidate|
+          found_idx = remove_accents(text.downcase).index(remove_accents(str_candidate.downcase))
+          idx = found_idx if idx.nil?
+          idx = found_idx if !found_idx.nil? && found_idx >= idx
+        end
+        idx
+      end
+
+      # Normalizes text by removing diacritics.
+      # @param input_str [String] string to handle.
+      # @return [String]
+      def self.remove_accents(input_str)
+        diacritics = [*0x1DC0..0x1DFF, *0x0300..0x036F, *0xFE20..0xFE2F].pack('U*')
+        input_str
+          .unicode_normalize(:nfd)
+          .tr(diacritics, '')
+          .unicode_normalize(:nfc)
+          .scrub
+      end
+
+      # Checks if a given percentage value is within the allowed range
+      # @param value [Integer] The value to check
+      # @param min_rate_percentage [Integer] Minimum allowed rate on the tax.
+      # @param max_rate_percentage [Integer] Maximum allowed rate on the tax.
+      # @return [Boolean]
+      def self.valid_percentage?(value, min_rate_percentage, max_rate_percentage)
+        return false if value.nil?
+
+        value > min_rate_percentage && value < max_rate_percentage
+      end
+
+      # Parses a percentage from a string, and returns it as a float.
+      # Returns nil if candidate isn't a valid percentage.
+      # @param percentage_str [String] String candidate.
+      # @return [Float, nil]
+      def self.parse_percentage(percentage_str)
+        percentage_str.gsub!('%', '')
+        percentage_str.strip
+        percentage_str.gsub!(',', '.')
+        Float(percentage_str.scrub)
+      rescue ArgumentError
+        nil
+      end
+
+      # Parses an amount from a string, and returns it as a float.
+      # Returns nil if candidate isn't a valid amount.
+      # @param amount_str [String] String candidate.
+      # @return [Float, nil]
+      def self.parse_amount(amount_str)
+        cleaned_str = amount_str.gsub(' ', '')
+        cleaned_str = standardize_delimiters(cleaned_str)
+        Float(cleaned_str)
+      rescue ArgumentError
+        nil
+      end
+
+      private
+
+      def self.standardize_delimiters(str)
+        if comma_decimal?(str)
+          str.gsub('.', '').gsub(',', '.')
+        elsif dot_decimal?(str)
+          str.gsub(',', '')
+        else
+          str
+        end
+      end
+
+      def self.comma_decimal?(str)
+        (str.length > 3 && str[-3] == ',') || str[-2] == ','
+      end
+
+      def self.dot_decimal?(str)
+        (str.length > 3 && str[-3] == '.') || str[-2] == '.'
+      end
+
+      # Removes most common currency symbols from string
+      # @param input_string [String] string to remove the symbols from
+      # @return [String]
+      def self.remove_currency_symbols(input_string)
+        # Define an array of common currency symbols
+        currency_symbols = ['$', '€', '£', '¥', '₹', '₽', '฿', '₺', '₴', '₿', '₡', '₮', '₱', '₲', '₪', '₫', '₩', '₵',
+                            '₦', '₢', '₤', '₣', '₧', '₯', '₠', '₶', '₸', '₷', '₼', '₾', '₺', '﹩', '₨', '₹', '＄', '﹫']
+
+        # Iterate over each currency symbol and remove it from the input string
+        currency_symbols.each do |symbol|
+          input_string.gsub!(symbol, '')
+        end
+
+        input_string
+      end
+
+      private_class_method :remove_accents, :match_index, :parse_amount, :parse_percentage, :remove_currency_symbols,
+                           :valid_percentage?, :comma_decimal?, :dot_decimal?, :standardize_delimiters
+    end
+  end
+end

data/lib/mindee/extraction/tax_extractor.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require_relative 'ocr_extractor'
+
+module Mindee
+  module Extraction
+    # Tax extractor class
+    class TaxExtractor < OcrExtractor
+      # Extracts the most relevant candidate.
+      # @param candidates [Array<Hash>] a candidate for the tax.
+      # @param tax_names [Array<String>] list of all possible names the tax can have.
+      # @return [Hash, nil]
+      def self.pick_best(candidates, tax_names)
+        return candidates[0] if candidates.size == 1
+        return nil if candidates.empty?
+
+        picked = 0
+        picked_score = 0
+
+        candidates.each_with_index do |candidate, i|
+          next unless valid_candidate?(candidate, tax_names)
+
+          sum_fields_score = calculate_score(candidate, i)
+
+          if picked_score < sum_fields_score
+            picked_score = sum_fields_score
+            picked = i
+          end
+        end
+
+        candidates[picked]
+      end
+
+      # Checks whether a tax code has been properly read. Shouldn't trigger except in case of very specific regex breaks
+      # due to unsupported diacritics.
+      # @param candidate [Hash] A candidate for the tax.
+      # @param tax_names [Array<String>] list of all possible names the tax can have.
+      # @return [Boolean]
+      def self.valid_candidate?(candidate, tax_names)
+        return false if tax_names.empty? || candidate.nil? || candidate['code'].nil?
+
+        tax_names.each do |tax_name|
+          return true if remove_accents(tax_name.downcase) == remove_accents(candidate['code'].downcase)
+        end
+        false
+      end
+
+      # [Experimental] computes the score of a valid candidate for a tax.
+      # @param candidate [Hash] A candidate for the tax.
+      # @param index [Integer]
+      def self.calculate_score(candidate, index)
+        score = index + 1
+        unless candidate['rate'].nil?
+          score += 1
+          score -= 2 if candidate['rate'] > 100
+          score -= 1 if candidate['rate'] > 30
+        end
+        score += 4 unless candidate['value'].nil?
+        score += 1 unless candidate['base'].nil?
+        score
+      end
+
+      # Curates tax values based on simple rules to avoid improbable data
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @param min_rate_percentage [Integer] Minimum allowed rate on the tax.
+      # @param max_rate_percentage [Integer] Maximum allowed rate on the tax.
+      # @return [Hash]
+      def self.curate_values(found_hash, min_rate_percentage, max_rate_percentage)
+        reconstructed_hash = { 'code' => nil, 'page_id' => nil, 'rate' => nil, 'base' => nil, 'value' => nil }
+        return reconstructed_hash if found_hash.nil?
+
+        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
+        end
+        found_hash = swap_rates_if_needed(found_hash, min_rate_percentage, max_rate_percentage)
+        found_hash = decimate_rates_if_needed(found_hash)
+        found_hash = fix_rate(found_hash)
+        reconstructed_hash['rate'] = found_hash['rate']
+        set_base_and_value(reconstructed_hash, found_hash)
+      end
+
+      # Swaps the rate with base or value if rate is out of bounds
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @param min_rate_percentage [Integer] Minimum allowed rate on the tax.
+      # @param max_rate_percentage [Integer] Maximum allowed rate on the tax.
+      # @return [Hash]
+      def self.swap_rates_if_needed(found_hash, min_rate_percentage, max_rate_percentage)
+        if found_hash['rate'] && (found_hash['rate'] > max_rate_percentage || found_hash['rate'] < min_rate_percentage)
+          if valid_percentage?(found_hash['base'], min_rate_percentage, max_rate_percentage)
+            found_hash['rate'], found_hash['base'] = found_hash['base'], found_hash['rate']
+          elsif valid_percentage?(found_hash['value'], min_rate_percentage, max_rate_percentage)
+            found_hash['rate'], found_hash['value'] = found_hash['value'], found_hash['rate']
+          end
+        end
+        found_hash
+      end
+
+      # Rates can't be negative if set.
+      # @param found_hash [Hash] Hash of currently retrieved values
+      def self.fix_rate(found_hash)
+        found_hash['rate'] = found_hash['rate'].abs unless found_hash['rate'].nil?
+        found_hash
+      end
+
+      # Swaps the rate with base or value if rate is out of bounds
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @return [Hash]
+      def self.decimate_rates_if_needed(found_hash)
+        if found_hash['rate'] && found_hash['rate'] > 100
+          if !found_hash['base'].nil? && found_hash['rate'] > found_hash['base']
+            found_hash['rate'], found_hash['base'] = found_hash['base'], found_hash['rate']
+          elsif !found_hash['value'].nil? && found_hash['rate'] > found_hash['value']
+            found_hash['rate'], found_hash['value'] = found_hash['value'], found_hash['rate']
+          end
+        end
+        found_hash
+      end
+
+      # Sets the base and value in the reconstructed hash based on certain conditions
+      # @param reconstructed_hash [Hash] Hash being reconstructed with new values
+      # @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']
+        end
+        reconstructed_hash
+      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.
+      # @param tax_names [Array<String>] list of all possible names the tax can have.
+      # @param min_rate_percentage [Integer] Minimum allowed rate on the tax.
+      # @param max_rate_percentage [Integer] Maximum allowed rate on the tax.
+      # @return [Mindee::Parsing::Standard::TaxField, nil]
+      def self.extract_custom_tax(ocr_result, tax_names, min_rate_percentage = 0, max_rate_percentage = 100)
+        return nil if ocr_result.is_a?(Mindee::Parsing::Common::Ocr) || tax_names.empty?
+
+        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)
+        end
+        found_hash = curate_values(found_hash, min_rate_percentage, max_rate_percentage)
+
+        return if found_hash.nil? || found_hash.empty?
+
+        create_tax_field(found_hash)
+      end
+
+      # Creates a tax field from a given hash.
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @return [Mindee::Parsing::Standard::TaxField]
+      def self.create_tax_field(found_hash)
+        Mindee::Parsing::Standard::TaxField.new(
+          found_hash,
+          found_hash.key?('page_id') ? found_hash['page_id'] : nil
+        )
+      end
+
+      # Extracts the rate and code, if found, from matches into the found_hash.
+      # @param matches [MatchData] RegEx matches of the values for taxes
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @param percent_first [Boolean] Whether the percentage was found before or after the tax name.
+      # @return [Hash]
+      def self.extract_percentage_from_tax(matches, found_hash, percent_first)
+        if percent_first
+          found_hash['code'] = matches[2].strip unless matches[2].nil?
+          found_hash['rate'] = parse_amount(matches[1].gsub('%', '')) unless matches[1].nil?
+        else
+          found_hash['code'] = matches[1].strip unless matches[1].nil?
+          found_hash['rate'] = parse_amount(matches[2].gsub('%', '')) unless matches[2].nil?
+        end
+        found_hash
+      end
+
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+
+      # Extracts the basis and value of a tax from regex matches, independent of the order.
+      # @param matches [MatchData] RegEx matches of the values for taxes
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @return [Hash]
+      def self.extract_basis_and_value(matches, found_hash)
+        if matches[4].nil? && !matches[3].nil?
+          found_hash['value'] = parse_amount(matches[3]) unless matches[3].nil?
+        elsif matches[3].nil? && !matches[4].nil?
+          found_hash['value'] = parse_amount(matches[4]) unless matches[4].nil?
+        elsif !matches[3].nil? && !matches[4].nil?
+          found_hash['base'] = parse_amount(matches[3]) unless matches[3].nil?
+          found_hash['value'] = parse_amount(matches[4]) unless matches[4].nil?
+        end
+        found_hash
+      end
+
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      # Extracts tax information from a horizontal line.
+      # @param line [String] Line to be processed.
+      # @param pattern [Regexp] RegEx pattern to search the line with.
+      # @param percent_first [Boolean] Whether the percentage was found before or after the tax name.
+      # @return [Hash]
+      def self.extract_tax_from_horizontal_line(line, pattern, page_id, percent_first)
+        found_hash = {}
+
+        matches = line.match(pattern)
+
+        # Edge case for when the tax is split-up between two pages, we'll consider that
+        # the answer belongs to the first one.
+        found_hash['page_id'] = page_id unless found_hash.key?('page_id')
+        return found_hash if matches.nil?
+
+        found_hash = extract_percentage_from_tax(matches, found_hash, percent_first)
+        extract_basis_and_value(matches, found_hash)
+      end
+
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+
+      # Processes a horizontal line for tax extraction. Returns a hash of collected values.
+      # @param ocr_result [Mindee::Parsing::Common::Ocr::Ocr] Processed OCR results.
+      # @param tax_names [Array<String>] Possible tax names candidates.
+      # @return [Array<Hash>]
+      def self.extract_horizontal_tax(ocr_result, tax_names)
+        candidates = [{ 'code' => nil, 'value' => nil, 'base' => nil, 'rate' => nil }]
+        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,})?
+        }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,})?
+        }x
+        ocr_result.mvision_v1.pages.each.with_index do |page, page_id|
+          page.all_lines.each do |line|
+            clean_line = remove_currency_symbols(line.to_s.scrub.gsub(%r{[+(\[)\]¿?*_]}, '')).gsub(%r{\.{2,}}, ' ')
+                                                                                             .gsub(%r{ +}, ' ').strip
+
+            next if match_index(clean_line, tax_names).nil?
+
+            unless clean_line.match(linear_pattern_percent_second).nil?
+              candidates.append(extract_tax_from_horizontal_line(clean_line[match_index(clean_line, tax_names)..],
+                                                                 linear_pattern_percent_second, page_id, false))
+            end
+            if clean_line.include?('%') && !clean_line.match(linear_pattern_percent_first).nil?
+              candidates.append(extract_tax_from_horizontal_line(clean_line[clean_line.index(%r{\d*[.,]?\d* ?%})..],
+                                                                 linear_pattern_percent_first, page_id, true))
+            elsif !clean_line.match(linear_pattern_percent_first).nil?
+              candidates.append(extract_tax_from_horizontal_line(clean_line,
+                                                                 linear_pattern_percent_first, page_id, true))
+            end
+          end
+        end
+        candidates
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      # Processes a vertical reconstructed line for tax extraction. Returns a hash of collected values.
+      # @param line [Mindee::Parsing::Common::Ocr::OcrLine] Processed OCR results.
+      # @param found_hash [Hash] Hash containing previously found values, if any.
+      # @return [Hash]
+      def self.extract_vertical_tax_values(line, found_hash)
+        amounts = []
+        line.each do |reconstructed_word|
+          amounts.push(parse_amount(reconstructed_word.text)) unless parse_amount(reconstructed_word.text).nil?
+        end
+        if amounts.length == 1 && !found_hash.key?('value')
+          found_hash['value'] = amounts[0]
+        else
+          found_hash['rate'] = amounts[0] if found_hash['rate'].nil?
+          found_hash['value'] = amounts[1] if found_hash['value'].nil?
+        end
+        found_hash
+      end
+
+      # Extracts tax data from a vertical reconstructed row.
+      # @param ocr_result [Mindee::Parsing::Common::Ocr] OCR raw results
+      # @param tax_names [Array<String>] Array of possible names a tax can have
+      # @param found_hash [Hash] Hash of currently retrieved values
+      def self.extract_vertical_tax(ocr_result, tax_names, found_hash)
+        found_hash = { 'code' => nil, 'page_id' => nil } if found_hash.nil?
+
+        ocr_result.mvision_v1.pages.each_with_index do |page, page_id|
+          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)
+            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)
+          end
+        end
+        found_hash
+      end
+
+      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
+    end
+  end
+end

data/lib/mindee/extraction.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'extraction/tax_extractor'

data/lib/mindee/geometry/utils.rb

@@ -77,5 +77,24 @@ module Mindee
       coords = points.map(&:x)
       MinMax.new(coords.min, coords.max)
     end
+
+    # Checks whether a set of coordinates is below another on the page, with a slight margin for the lateral value.
+    # @param candidate [Array<Mindee::Geometry::Point] Polygon to check
+    # @param anchor [Array<Mindee::Geometry::Point] Reference polygon
+    # @param margin_left [Float] Margin tolerance on the left of the anchor
+    # @param margin_right [Float] Margin tolerance on the right of the anchor
+    def self.below?(candidate, anchor, margin_left, margin_right)
+      return false if Geometry.get_min_max_y(candidate).min < Geometry.get_min_max_y(anchor).min
+      if Geometry.get_min_max_x(candidate).min <
+         Geometry.get_min_max_x(anchor).min - (Geometry.get_min_max_x(anchor).min * margin_left)
+        return false
+      end
+      if Geometry.get_min_max_x(candidate).max >
+         Geometry.get_min_max_x(anchor).max + (Geometry.get_min_max_x(anchor).max * margin_right)
+        return false
+      end
+
+      true
+    end
   end
 end