mindee 4.13.0 → 5.0.0.rc1

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative '../../standard/position_field'
+
+module Mindee
+  module V1
+    module Parsing
+      module Common
+        # Extras namespace.
+        module Extras
+          # Extra information added to the prediction.
+          class Extras
+            # @return [CropperExtra, nil]
+            attr_reader :cropper
+            # @return [Mindee::V1::Parsing::Common::Extras::FullTextOCRExtra]
+            attr_reader :full_text_ocr
+            # @return [RAGExtra, nil]
+            attr_reader :rag
+
+            def initialize(raw_prediction)
+              if raw_prediction['cropper']
+                @cropper = Mindee::V1::Parsing::Common::Extras::CropperExtra.new(raw_prediction['cropper'])
+              end
+              if raw_prediction['full_text_ocr']
+                @full_text_ocr = Mindee::V1::Parsing::Common::Extras::FullTextOCRExtra.new(
+                  raw_prediction['full_text_ocr']
+                )
+              end
+              @rag = Mindee::V1::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.to_s)
+              end
+            end
+
+            # @return [String]
+            def to_s
+              out_str = String.new
+              instance_variables.each do |var|
+                out_str << "#{var}: #{instance_variable_get(var)}"
+              end
+              out_str
+            end
+
+            # Adds artificial extra data for reconstructed extras. Currently only used for full_text_ocr.
+            #
+            # @param [Hash] raw_prediction Raw prediction used by the document.
+            def add_artificial_extra(raw_prediction)
+              return unless raw_prediction['full_text_ocr']
+
+              @full_text_ocr << Mindee::V1::Parsing::Common::Extras::FullTextOCRExtra.new(raw_prediction)
+            end
+          end
+
+          def empty?
+            instance_variables.all? { |var| instance_variable_get(var).nil? }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../../standard/position_field'
+
+module Mindee
+  module V1
+    module Parsing
+      module Common
+        module Extras
+          # Full Text OCR result.
+          class FullTextOCRExtra
+            # Contents of the full text OCR result.
+            # @return [String, nil]
+            attr_reader :contents
+            # Language used on the page.
+            # @return [String, nil]
+            attr_reader :language
+
+            def initialize(raw_prediction)
+              @contents = raw_prediction['content'] if raw_prediction['content']
+              return unless raw_prediction['language']
+
+              @language = raw_prediction['language']
+            end
+
+            # @return [String]
+            def to_s
+              @contents || ''
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V1
+    module Parsing
+      module Common
+        module Extras
+          # Retrieval-Augmented Generation extra.
+          class RAGExtra
+            # ID of the matching document
+            # @return [String, nil]
+            attr_reader :matching_document_id
+
+            def initialize(raw_prediction)
+              @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
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/v1/parsing/common/inference.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'product'
+
+module Mindee
+  module V1
+    module Parsing
+      # Common fields used for most documents.
+      module Common
+        # Abstract class for prediction Inferences
+        # Holds prediction for a page or entire document.
+        class Inference
+          # @return [bool]
+          attr_reader :is_rotation_applied
+          # @return [Array<Mindee::V1::Parsing::Common::Page>]
+          attr_reader :pages
+          # @return [Mindee::V1::Parsing::Common::Prediction]
+          attr_reader :prediction
+          # @return [Mindee::V1::Parsing::Common::Product]
+          attr_reader :product
+          # Name of the endpoint for this product.
+          # @return [String]
+          attr_reader :endpoint_name
+          # Version for this product.
+          # @return [String]
+          attr_reader :endpoint_version
+          # Whether this product has access to an asynchronous endpoint.
+          # @return [bool]
+          attr_reader :has_async
+          # Whether this product has access to synchronous endpoint.
+          # @return [bool]
+          attr_reader :has_sync
+          # @return [Mindee::V1::Parsing::Common::Extras::Extras] Potential Extras fields sent back along the prediction
+          attr_reader :extras
+
+          @endpoint_name = nil
+          @endpoint_version = nil
+          @has_async = false
+          @has_sync = false
+
+          # @param raw_prediction [Hash]
+          def initialize(raw_prediction)
+            @is_rotation_applied = raw_prediction['is_rotation_applied']
+            @product = Product.new(raw_prediction['product'])
+            @pages = [] # : Array[Page]
+            @extras = Extras::Extras.new(raw_prediction['extras']) if raw_prediction.include?('extras')
+          end
+
+          # @return [String]
+          def to_s
+            is_rotation_applied = @is_rotation_applied ? 'Yes' : 'No'
+            out_str = String.new
+            out_str << "Inference\n#########"
+            out_str << "\n:Product: #{@product.name} v#{@product.version}"
+            out_str << "\n:Rotation applied: #{is_rotation_applied}"
+            out_str << "\n\nPrediction\n=========="
+            out_str << "\n#{"#{@prediction}\n" if @prediction.to_s.size.positive?}"
+            if @pages.any? { |page| !page.prediction.nil? }
+              out_str << "\nPage Predictions\n================\n\n"
+              out_str << @pages.join("\n\n")
+            end
+            out_str.rstrip!
+            out_str
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/v1/parsing/common/job.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Mindee
+  module V1
+    module Parsing
+      module Common
+        # Job (queue) information on async parsing.
+        class Job
+          # @return [String] Mindee ID of the document
+          attr_reader :id
+          # @return [Time]
+          attr_reader :issued_at
+          # @return [Time, nil]
+          attr_reader :available_at
+          # @return [JobStatus, Symbol]
+          attr_reader :status
+          # @return [Integer, nil]
+          attr_reader :millisecs_taken
+          # @return [Hash, nil]
+          attr_reader :error
+
+          # @param http_response [Hash]
+          def initialize(http_response)
+            @id = http_response['id']
+            @error = http_response['error']
+            @issued_at = Time.iso8601(http_response['issued_at'])
+            if http_response.key?('available_at') && !http_response['available_at'].nil?
+              @available_at = Time.iso8601(http_response['available_at'])
+              @millisecs_taken = (1000 * (@available_at.to_time - @issued_at.to_time).to_f).to_i
+            end
+            @status = case http_response['status']
+                      when 'waiting'
+                        JobStatus::WAITING
+                      when 'processing'
+                        JobStatus::PROCESSING
+                      when 'completed'
+                        JobStatus::COMPLETED
+                      else
+                        http_response['status']&.to_sym
+                      end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V1
+    module Parsing
+      module Common
+        module OCR
+          # Mindee Vision V1.
+          class MVisionV1
+            # List of pages.
+            # @return [Array<OCRPage>]
+            attr_reader :pages
+
+            # @param prediction [Hash]
+            def initialize(prediction)
+              @pages = [] # : Array[Mindee::V1::Parsing::Common::OCR::OCRPage]
+              prediction['pages'].each do |page_prediction|
+                @pages.push(OCRPage.new(page_prediction))
+              end
+            end
+
+            # @return [String]
+            def to_s
+              out_str = String.new
+              @pages.map do |page|
+                out_str << "\n"
+                out_str << page.to_s
+              end
+              out_str.strip
+            end
+
+            # Constructs a line from a column, located underneath given coordinates
+            # @param coordinates [Array<Mindee::Geometry::Point>] Polygon or bounding box where the reconstruction
+            # should start.
+            # @param page_id [Integer] ID of the page to start at
+            # @param x_margin [Float] Margin of misalignment for the x coordinate.
+            # @return [Mindee::V1::Parsing::Common::OCR::OCRLine]
+            def reconstruct_vertically(coordinates, page_id, x_margin)
+              line_arr = OCRLine.new([])
+              @pages[page_id].all_lines.each do |line|
+                line.each do |word|
+                  line_arr.push(word) if Geometry.below?(word.polygon, coordinates, x_margin / 2, x_margin * 2)
+                end
+              end
+              line_arr
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative 'mvision_v1'
+
+module Mindee
+  module V1
+    module Parsing
+      module Common
+        # OCR-specific parsing fields and options
+        module OCR
+          # A single word.
+          class OCRWord
+            # The confidence score, value will be between 0.0 and 1.0
+            # @return [Float]
+            attr_reader :confidence
+            # @return [String]
+            attr_reader :text
+            # @return [Mindee::Geometry::Quadrilateral]
+            attr_reader :bounding_box
+            # @return [Mindee::Geometry::Polygon]
+            attr_reader :polygon
+
+            # @param prediction [Hash]
+            def initialize(prediction)
+              @text = prediction['text']
+              @confidence = prediction['confidence']
+              @polygon = Mindee::Geometry::Polygon.new(prediction['polygon'])
+              @bounding_box = Geometry.get_bounding_box(@polygon) unless @polygon.nil? || @polygon.empty?
+            end
+
+            # @return [String]
+            def to_s
+              @text.to_s
+            end
+          end
+
+          # A list of words which are on the same line.
+          class OCRLine < Array
+            # @param prediction [Hash, 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) })
+              elsif !from_array.nil?
+                super(from_array)
+              end
+            end
+
+            # Sort the words on the line from left to right.
+            # @return [OCRLine]
+            def sort_on_x
+              from_array = sort_by { |word| Geometry.get_min_max_x(word.polygon).min }
+              OCRLine.new(nil, from_array)
+            end
+
+            # @return [String]
+            def to_s
+              each(&:to_s).join(' ')
+            end
+          end
+
+          # OCR extraction for a single page.
+          class OCRPage
+            # All the words on the page, in semi-random order.
+            # @return [Array<OCRWord>]
+            attr_reader :all_words
+            # @return [Array<OCRLine>]
+            attr_reader :lines
+
+            # @param prediction [Hash]
+            def initialize(prediction)
+              @lines = [] # : Array[Mindee::V1::Parsing::Common::OCR::OCRLine]
+              @all_words = [] # : Array[Mindee::V1::Parsing::Common::OCR::OCRWord]
+              prediction['all_words'].each do |word_prediction|
+                @all_words.push(OCRWord.new(word_prediction))
+              end
+            end
+
+            # All the words on the page, ordered in lines.
+            # @return [Array<OCRLine>]
+            def all_lines
+              @lines = to_lines if @lines.empty?
+              @lines
+            end
+
+            # @return [String]
+            def to_s
+              lines = all_lines
+              return '' if lines.empty?
+
+              out_str = String.new
+              lines.map do |line|
+                out_str << "#{line}\n" unless line.to_s.strip.empty?
+              end
+              out_str.strip
+            end
+
+            private
+
+            # Helper function that iterates through all the words and compares them to a candidate
+            # @param sorted_words [Array<OCRWord>]
+            # @param current [OCRWord]
+            # @param indexes [Array<Integer>]
+            # @param lines [Array<OCRLine>]
+            def parse_one(sorted_words, current, indexes, lines)
+              line = OCRLine.new(nil, [])
+              sorted_words.each_with_index do |word, idx|
+                next if indexes.include?(idx)
+
+                if current.nil?
+                  current = word
+                  indexes.push(idx)
+                  line = OCRLine.new([])
+                  line.push(word)
+                elsif words_on_same_line?(current, word)
+                  line.push(word)
+                  indexes.push(idx)
+                end
+              end
+              lines.push(line.sort_on_x) if line.any?
+            end
+
+            # Order all the words on the page into lines.
+            # @return [Array<OCRLine>]
+            def to_lines
+              current = nil
+              indexes = [] # : Array[Integer]
+              lines = [] # : Array[Mindee::V1::Parsing::Common::OCR::OCRLine]
+
+              # make sure words are sorted from top to bottom
+              all_words = @all_words.sort_by { |word| Geometry.get_min_max_y(word.polygon).min }
+              all_words.each do
+                parse_one(all_words, current, indexes, lines)
+                current = nil
+              end
+              lines
+            end
+
+            # Determine if two words are on the same line.
+            # @param current_word [Mindee::V1::Parsing::Common::OCR::OCRWord]
+            # @param next_word [Mindee::V1::Parsing::Common::OCR::OCRWord]
+            # @return [bool]
+            def words_on_same_line?(current_word, next_word)
+              current_in_next = current_word.polygon.point_in_y?(next_word.polygon.centroid)
+              next_in_current = next_word.polygon.point_in_y?(current_word.polygon.centroid) unless current_word.nil?
+              current_in_next || next_in_current
+            end
+          end
+
+          # OCR extraction from the entire document.
+          class OCR
+            # Mindee Vision v1 results.
+            # @return [Mindee::V1::Parsing::Common::OCR::MVisionV1]
+            attr_reader :mvision_v1
+
+            # @param prediction [Hash]
+            def initialize(prediction)
+              @mvision_v1 = Mindee::V1::Parsing::Common::OCR::MVisionV1.new(prediction['mvision-v1'])
+            end
+
+            # @return [String]
+            def to_s
+              @mvision_v1.to_s
+            end
+
+            # Constructs a line from a column, located underneath given coordinates
+            # @param coordinates [Array<Mindee::Geometry::Point>] Polygon or bounding box where the reconstruction
+            # should start
+            # @param page_id [Integer] ID of the page to start at
+            # @param x_margin [Float] Margin of misalignment for the x coordinate (default 10%)
+            # @return [Mindee::V1::Parsing::Common::OCR::OCRLine]
+            def reconstruct_vertically(coordinates, page_id, x_margin = 0.05)
+              @mvision_v1.reconstruct_vertically(coordinates, page_id, x_margin)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V1
+    module Parsing
+      module Common
+        # Page orientation
+        class Orientation
+          # @return [Integer, nil]
+          attr_reader :page_id
+          # A prediction among these 3 possible outputs:
+          #   * 0 degrees: the page is already upright
+          #   * 90 degrees: the page must be rotated clockwise to be upright
+          #   * 270 degrees: the page must be rotated counterclockwise to be upright
+          # @return [Integer, nil]
+          attr_reader :value
+
+          # @param prediction [Hash]
+          # @param page_id [Integer, nil]
+          def initialize(prediction, page_id)
+            @value = prediction['value']
+            @page_id = page_id
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/v1/parsing/common/page.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'product'
+require_relative 'extras'
+
+module Mindee
+  module V1
+    module Parsing
+      # Common fields used for most documents.
+      module Common
+        # Abstract wrapper class for prediction Pages
+        # Holds prediction for a page as well as it's orientation and  id.
+        class Page
+          # ID of the page (as given by the API).
+          # @return [Integer]
+          attr_reader :page_id
+          # Orientation of the page.
+          # @return [Mindee::V1::Parsing::Common::Orientation]
+          attr_reader :orientation
+          # Page prediction
+          # @return [Mindee::V1::Parsing::Common::Prediction]
+          attr_reader :prediction
+          # Additional page-level information.
+          # @return [Mindee::V1::Parsing::Common::Extras::Extras]
+          attr_reader :extras
+
+          # @param raw_prediction [Hash]
+          def initialize(raw_prediction)
+            @page_id = raw_prediction['id']
+            @orientation = Mindee::V1::Parsing::Common::Orientation.new(raw_prediction['orientation'], @page_id)
+            return if raw_prediction['extras'].nil?
+
+            @extras = Mindee::V1::Parsing::Common::Extras::Extras.new(raw_prediction['extras'])
+          end
+
+          # @return [String]
+          def to_s
+            out_str = String.new
+            title = "Page #{@page_id}"
+            out_str << "#{title}\n"
+            out_str << ('-' * title.size)
+            out_str << @prediction.to_s
+            out_str
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/v1/parsing/common/prediction.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V1
+    module Parsing
+      module Common
+        # Abstract class for all predictions
+        class Prediction
+          # @return [String]
+          def to_s
+            ''
+          end
+
+          def initialize(_ = nil, _ = nil); end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V1
+    module Parsing
+      module Common
+        # Product information
+        class Product
+          # @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)
+            @name = prediction['name']
+            @type = prediction['type']
+            @version = prediction['version']
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/v1/parsing/common/workflow_response.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V1
+    module Parsing
+      module Common
+        # Represents the server response after a document is sent to a workflow.
+        class WorkflowResponse
+          # Set the prediction model used to parse the document.
+          # The response object will be instantiated based on this parameter.
+          # @return [Mindee::V1::Parsing::Common::Execution]
+          attr_reader :execution
+          # @return [Mindee::V1::Parsing::Common::ApiRequest]
+          attr_reader :api_request
+          # @return [String]
+          attr_reader :raw_http
+
+          # @param http_response [Hash]
+          # @param product_class [Mindee::Inference]
+          def initialize(product_class, http_response, raw_http)
+            @raw_http = raw_http.to_s
+            @api_request = Mindee::V1::Parsing::Common::ApiRequest.new(http_response['api_request'])
+            product_class ||= Mindee::V1::Product::Universal::Universal
+            @execution = Mindee::V1::Parsing::Common::Execution.new(product_class, http_response['execution'])
+          end
+        end
+      end
+    end
+  end
+end