mindee 4.6.0 → 4.7.0.pre.rc2

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]
@@ -47,8 +47,7 @@ module Mindee
           end
 
           if filename.end_with?('.pdf') && repair_pdf
-            rescue_broken_pdf(@io_stream)
-            @file_mimetype = Marcel::MimeType.for @io_stream
+            fix_pdf!
 
             logger.debug("Loaded new input #{@filename} from #{self.class}")
             return if ALLOWED_MIME_TYPES.include? @file_mimetype
@@ -57,28 +56,41 @@ module Mindee
           raise Errors::MindeeMimeTypeError, @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 Errors::MindeePDFError if stream.eof? || stream.pos > 500
-
-          stream.pos = stream.pos - 5
-          data = stream.read
-          @io_stream.close
-
-          @io_stream = StringIO.new
-          @io_stream << data
+        # @deprecated See {#fix_pdf!} or {#self.fix_pdf} instead.
+        def rescue_broken_pdf(_)
+          fix_pdf!
         end
 
-        # Shorthand for pdf mimetype validation.
+        # Shorthand for PDF mimetype validation.
         def pdf?
           @file_mimetype.to_s == 'application/pdf'
         end
 
-        # Parses a PDF file according to provided options.
+        # Attempts to fix the PDF data in the file.
+        # @param maximum_offset [Integer] Maximum offset to look for the PDF header.
+        # @return [void]
+        # @raise [Mindee::Errors::MindeePDFError]
+        def fix_pdf!(maximum_offset: 500)
+          @io_stream = LocalInputSource.fix_pdf(@io_stream, maximum_offset: maximum_offset)
+          @io_stream.rewind
+          @file_mimetype = Marcel::MimeType.for @io_stream
+        end
+
+        # Attempt to fix the PDF data in the given stream.
+        # @param stream [StringIO] The stream to fix.
+        # @param maximum_offset [Integer] Maximum offset to look for the PDF header.
+        # @return [StringIO] The fixed stream.
+        # @raise [Mindee::Errors::MindeePDFError]
+        def self.fix_pdf(stream, maximum_offset: 500)
+          out_stream = StringIO.new
+          stream.gets('%PDF-')
+          raise Errors::MindeePDFError if stream.eof? || stream.pos > maximum_offset
+
+          stream.pos = stream.pos - 5
+          out_stream << stream.read
+        end
+
+        # 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 +98,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 +119,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
@@ -159,8 +178,8 @@ module Mindee
           @io_stream.rewind
         end
 
-        # Checks whether the file has source text if it is a pdf. False otherwise
-        # @return [bool] True if the file is a PDF and has source text.
+        # Checks whether the file has source text if it is a pdf. `false` otherwise
+        # @return [bool] `true` if the file is a PDF and has source text.
         def source_text?
           Mindee::PDF::PDFTools.source_text?(@io_stream)
         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

data/lib/mindee/parsing/common/api_request.rb

@@ -8,7 +8,7 @@ module Mindee
         # @return [Hash]
         attr_reader :error
         # @return [Array<String>]
-        attr_reader :ressources
+        attr_reader :resources
         # @return [RequestStatus, Symbol]
         attr_reader :status
         # @return [Integer]
@@ -18,7 +18,7 @@ module Mindee
 
         def initialize(server_response)
           @error = server_response['error']
-          @ressources = server_response['ressources']
+          @resources = server_response['resources']
 
           @status = if server_response['status'] == 'failure'
                       RequestStatus::FAILURE

data/lib/mindee/parsing/common/api_response.rb

@@ -8,9 +8,13 @@ module Mindee
     module Common
       # Potential values for queue in asynchronous calls.
       module JobStatus
+        # Job is waiting.
         WAITING    = :waiting
+        # Job is processing.
         PROCESSING = :processing
+        # Job is done.
         COMPLETED  = :completed
+        # Job failed.
         FAILURE    = :failed
       end
 

data/lib/mindee/parsing/common/execution.rb

@@ -21,7 +21,7 @@ module Mindee
         # @return [Mindee::Inference]
         attr_reader :inference
         # Priority of the execution.
-        # @return [ExecutionPriority]
+        # @return [ExecutionPriority, Symbol, nil]
         attr_reader :priority
         # The time at which the file was tagged as reviewed.
         # @return [Time, nil]

data/lib/mindee/parsing/common/extras/extras.rb

@@ -11,7 +11,7 @@ module Mindee
         class Extras
           # @return [CropperExtra, nil]
           attr_reader :cropper
-          # @return [Mindee::Parsing::Common::Extras::FullTextOCRExtra, nil]
+          # @return [Mindee::Parsing::Common::Extras::FullTextOCRExtra]
           attr_reader :full_text_ocr
           # @return [RAGExtra, nil]
           attr_reader :rag
@@ -26,7 +26,7 @@ module Mindee
             @rag = Mindee::Parsing::Common::Extras::RAGExtra.new(raw_prediction['rag']) if raw_prediction['rag']
 
             raw_prediction.each do |key, value|
-              instance_variable_set("@#{key}", value) unless ['cropper', 'full_text_ocr', 'rag'].include?(key)
+              instance_variable_set("@#{key}", value) unless ['cropper', 'full_text_ocr', 'rag'].include?(key.to_s)
             end
           end
 

data/lib/mindee/parsing/common/extras/rag_extra.rb

@@ -14,6 +14,8 @@ module Mindee
             @matching_document_id = raw_prediction['matching_document_id'] if raw_prediction['matching_document_id']
           end
 
+          # String representation.
+          # @return [String]
           def to_s
             @matching_document_id || ''
           end

data/lib/mindee/parsing/common/ocr/ocr.rb

@@ -11,7 +11,7 @@ module Mindee
         class OCRWord
           # The confidence score, value will be between 0.0 and 1.0
           # @return [Float]
-          attr_accessor :confidence
+          attr_reader :confidence
           # @return [String]
           attr_reader :text
           # @return [Mindee::Geometry::Quadrilateral]
@@ -36,7 +36,7 @@ module Mindee
         # A list of words which are on the same line.
         class OCRLine < Array
           # @param prediction [Hash, nil]
-          # @param from_array [Array, nil]
+          # @param from_array [Array<OCRWord>, nil]
           def initialize(prediction = nil, from_array = nil)
             if !prediction.nil?
               super(prediction.map { |word_prediction| OCRWord.new(word_prediction) })
@@ -48,9 +48,7 @@ module Mindee
           # Sort the words on the line from left to right.
           # @return [OCRLine]
           def sort_on_x
-            from_array = sort do |word1, word2|
-              Geometry.get_min_max_x(word1.polygon).min <=> Geometry.get_min_max_x(word2.polygon).min
-            end
+            from_array = sort_by { |word| Geometry.get_min_max_x(word.polygon).min }
             OCRLine.new(nil, from_array)
           end
 
@@ -104,7 +102,7 @@ module Mindee
           # @param indexes [Array<Integer>]
           # @param lines [Array<OCRLine>]
           def parse_one(sorted_words, current, indexes, lines)
-            line = OCRLine.new([])
+            line = OCRLine.new(nil, [])
             sorted_words.each_with_index do |word, idx|
               next if indexes.include?(idx)
 

data/lib/mindee/parsing/common/orientation.rb

@@ -5,7 +5,7 @@ module Mindee
     module Common
       # Page orientation
       class Orientation
-        # @return [Integer]
+        # @return [Integer, nil]
         attr_reader :page_id
         # A prediction among these 3 possible outputs:
         #   * 0 degrees: the page is already upright
@@ -15,7 +15,7 @@ module Mindee
         attr_reader :value
 
         # @param prediction [Hash]
-        # @param page_id [Integer]
+        # @param page_id [Integer, nil]
         def initialize(prediction, page_id)
           @value = prediction['value']
           @page_id = page_id

data/lib/mindee/parsing/common/product.rb

@@ -5,7 +5,12 @@ module Mindee
     module Common
       # Product information
       class Product
-        attr_reader :name, :type, :version
+        # @return [String] Name of the product.
+        attr_reader :name
+        # @return [String?] Type of product.
+        attr_reader :type
+        # @return [String] Product version.
+        attr_reader :version
 
         # @param prediction [Hash]
         def initialize(prediction)

data/lib/mindee/parsing/standard/amount_field.rb

@@ -13,12 +13,12 @@ module Mindee
 
         def initialize(prediction, page_id, reconstructed: false)
           super
-          @value = @value.round(3) unless @value.nil?
+          @value = @value.to_f.round(3).to_f unless @value.to_s.empty?
         end
 
         # @return [String]
         def to_s
-          BaseField.float_to_string(@value)
+          @value.nil? ? '' : BaseField.float_to_string(@value.to_f)
         end
       end
     end

data/lib/mindee/parsing/standard/feature_field.rb

@@ -16,7 +16,7 @@ module Mindee
           return in_str.to_s if max_col_size.nil?
 
           in_str = in_str.to_s.gsub(%r{[\n\r\t]}, "\n" => '\\n', "\r" => '\\r', "\t" => '\\t')
-          in_str.to_s.length <= max_col_size.to_i ? in_str.to_s : "#{in_str[0..max_col_size.to_i - 4]}..."
+          in_str.to_s.length <= max_col_size.to_i ? in_str.to_s : "#{in_str[0..(max_col_size.to_i - 4)]}..."
         end
       end
     end

data/lib/mindee/parsing/standard/tax_field.rb

@@ -52,7 +52,7 @@ module Mindee
           out_h[:code] = @code.nil? ? '' : @code
           out_h[:base] = @base.nil? ? '' : print_float(@base)
           out_h[:rate] = @rate.nil? ? '' : print_float(@rate).to_s
-          out_h[:value] = @value.nil? ? '' : print_float(@value).to_s
+          out_h[:value] = @value.to_s.empty? ? '' : print_float(@value.to_f).to_s
           out_h
         end
 

data/lib/mindee/parsing/universal/universal_list_field.rb

@@ -12,11 +12,11 @@ module Mindee
 
         # ID of the page (as given by the API).
         # @return [Integer]
-        attr_accessor :page_id
+        attr_reader :page_id
 
         # List of word values
         # @return [Array<UniversalObjectField, StringField>]
-        attr_accessor :values
+        attr_reader :values
 
         # ID of the page the object was found on.
         # List of word values.

data/lib/mindee/parsing/universal/universal_object_field.rb

@@ -15,15 +15,18 @@ module Mindee
         # @return [Float]
         attr_reader :confidence
         # Value as String
-        # @return [Hash<Symbol | String, untyped>, nil]
-        attr_accessor :raw_value
+        # @return [String]
+        attr_reader :raw_value
+        # All values
+        # @return [Hash]
+        attr_reader :all_values
 
         # ID of the page the object was found on.
         # Confidence with which the value was assessed.
         # Raw unprocessed value, as it was sent by the server.
 
         def initialize(raw_prediction, page_id = nil)
-          @all_values = {} # : Hash[Symbol | String, untyped]
+          @all_values = {} # : Hash[String | Symbol, untyped]
           item_page_id = nil
           raw_prediction.each do |name, value|
             case name
@@ -75,7 +78,7 @@ module Mindee
         #
         # @param method_name [Symbol] The name of the method being checked.
         # @param include_private [bool] Whether to include private methods in the check.
-        # @return [bool] True if the method can be responded to, false otherwise.
+        # @return [bool] `true` if the method can be responded to, false otherwise.
         def respond_to_missing?(method_name, include_private = false)
           @all_values.key?(method_name.to_s) || super
         end

data/lib/mindee/parsing/v2/common_response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    module V2
+      # Base class for inference and job responses on the V2 API.
+      class CommonResponse
+        # @return [Hash]
+        attr_reader :raw_http
+
+        # @param http_response [Hash]
+        def initialize(http_response)
+          @raw_http = http_response
+        end
+      end
+    end
+  end
+end

data/lib/mindee/parsing/v2/error_response.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    module V2
+      # Encapsulates information returned by the API when an error occurs.
+      class ErrorResponse
+        # @return [Integer] HTTP status code.
+        attr_reader :status
+        # @return [String] Error detail.
+        attr_reader :detail
+
+        # @param server_response [Hash] Raw JSON parsed into a Hash.
+        def initialize(server_response)
+          @status = server_response['status']
+          @detail = server_response['detail']
+        end
+
+        # String representation.
+        # @return [String]
+        def to_s
+          "Error\n=====\n:Status: #{@status}\n:Detail: #{@detail}"
+        end
+
+        # Hash representation
+        # @return [Hash] Hash representation of the object.
+        def as_hash
+          {
+            status: @status,
+            detail: @detail,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/mindee/parsing/v2/field/base_field.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    module V2
+      # Field submodule for V2.
+      module Field
+        # Base class for V2 fields.
+        class BaseField
+          # @return [Integer] Level of indentation for rst display.
+          attr_reader :indent_level
+
+          # @return [FieldConfidence, nil] Confidence score for the field.
+          attr_reader :confidence
+
+          # @return [Array<FieldLocation>] List of locations the field was found at.
+          attr_reader :locations
+
+          # @param raw_prediction [Hash] Raw prediction hash.
+          # @param indent_level [Integer] Level of indentation for rst display.
+          def initialize(raw_prediction, indent_level = 0)
+            @indent_level = indent_level
+            @confidence = raw_prediction.key?('confidence') ? raw_prediction['confidence'] : nil
+            @locations = if raw_prediction.key?('locations')
+                           raw_prediction['locations'].map do |location|
+                             FieldLocation.new(location)
+                           end
+                         else
+                           []
+                         end
+          end
+
+          # Factory method to create appropriate field types.
+          # @param raw_prediction [Hash] Raw prediction hash.
+          # @param indent_level [Integer] Level of indentation for rst display.
+          # @return [BaseField] Appropriate field instance.
+          # @raise [MindeeError] If the field type isn't recognized.
+          def self.create_field(raw_prediction, indent_level = 0)
+            if raw_prediction.key?('items')
+              require_relative 'list_field'
+              return ListField.new(raw_prediction, indent_level)
+            end
+
+            if raw_prediction.key?('fields')
+              require_relative 'object_field'
+              return ObjectField.new(raw_prediction, indent_level)
+            end
+
+            if raw_prediction.key?('value')
+              require_relative 'simple_field'
+              return SimpleField.new(raw_prediction, indent_level)
+            end
+
+            raise Errors::MindeeError, "Unrecognized field format in #{raw_prediction.to_json}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/parsing/v2/field/field_confidence.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    module V2
+      module Field
+        # Confidence level of a field as returned by the V2 API.
+        class FieldConfidence
+          # @return [String] The confidence level value.
+          attr_reader :value
+
+          # Absolute certainty about the field's extraction.
+          CERTAIN = 'Certain'
+          # High certainty about the field's extraction.
+          HIGH = 'High'
+          # Medium certainty about the field's extraction.
+          MEDIUM = 'Medium'
+          # Low certainty about the field's extraction.
+          LOW = 'Low'
+
+          # List of valid values, as frozen strings.
+          VALID_VALUES = [CERTAIN, HIGH, MEDIUM, LOW].freeze
+
+          # @param value [String] The confidence level value.
+          # @raise [ArgumentError] If the value is not a valid confidence level.
+          def initialize(value)
+            unless VALID_VALUES.include?(value)
+              raise ArgumentError,
+                    "Invalid confidence level: #{value}. Must be one of: #{VALID_VALUES.join(', ')}"
+            end
+
+            @value = value
+          end
+
+          # Create a FieldConfidence from a string value.
+          # @param value [String] The confidence level string.
+          # @return [FieldConfidence] The confidence instance.
+          def self.from_string(value)
+            new(value)
+          end
+
+          # Check if this is a certain confidence level.
+          # @return [Boolean] `true` if confidence is certain.
+          def certain?
+            @value == CERTAIN
+          end
+
+          # Check if this is a high confidence level.
+          # @return [Boolean] `true` if confidence is high.
+          def high?
+            @value == HIGH
+          end
+
+          # Check if this is a medium confidence level.
+          # @return [Boolean] `true` if confidence is medium.
+          def medium?
+            @value == MEDIUM
+          end
+
+          # Check if this is a low confidence level.
+          # @return [Boolean] `true` if confidence is low.
+          def low?
+            @value == LOW
+          end
+
+          # String representation of the confidence level.
+          # @return [String] The confidence level value.
+          def to_s
+            @value
+          end
+
+          # Compare two FieldConfidence instances.
+          # @param other [FieldConfidence] The other confidence to compare.
+          # @return [Boolean] `true` if they have the same value.
+          def ==(other)
+            other.is_a?(FieldConfidence) && @value == other.value
+          end
+
+          # Make instances comparable and hashable
+          alias eql? ==
+
+          # Inspect method for debugging.
+          # @return [String] Debug representation.
+          def inspect
+            "#<#{self.class.name}:#{@value}>"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/parsing/v2/field/field_location.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative '../../../geometry/polygon'
+
+module Mindee
+  module Parsing
+    module V2
+      module Field
+        # Location of a field.
+        class FieldLocation
+          # @return [Mindee::Geometry::Polygon, nil] Polygon corresponding to the field location.
+          attr_reader :polygon
+
+          # @return [Integer, nil] Page on which the field is located.
+          attr_reader :page
+
+          # @param server_response [Hash] Raw server response hash.
+          def initialize(server_response)
+            polygon_data = server_response['polygon'] || server_response[:polygon]
+            @polygon = polygon_data ? Mindee::Geometry::Polygon.new(polygon_data) : nil
+
+            page_id = server_response['page'] || server_response[:page]
+            @page = page_id.is_a?(Float) || page_id.is_a?(Integer) ? page_id.to_i : nil
+          end
+
+          # String representation of the polygon (empty string when none).
+          #
+          # @return [String]
+          def to_s
+            @polygon ? @polygon.to_s : ''
+          end
+        end
+      end
+    end
+  end
+end