mindee 2.2.0 → 3.0.0

data/lib/mindee/client.rb

@@ -1,33 +1,27 @@
 # frozen_string_literal: true
 
 require_relative 'input'
-require_relative 'document_config'
-require_relative 'http/endpoint'
-require_relative 'parsing/prediction'
+require_relative 'http'
+require_relative 'product'
+require_relative 'parsing/common/api_response'
 
 module Mindee
-  # General client for sending a document to the API.
-  class DocumentClient
-    # @param input_doc [Mindee::InputDocument]
-    # @param doc_configs [Hash]
-    def initialize(input_doc, doc_configs)
-      @input_doc = input_doc
-      @doc_configs = doc_configs
+  # Mindee API Client.
+  # See: https://developers.mindee.com/docs
+  class Client
+    # @param api_key [String]
+    def initialize(api_key: '')
+      @api_key = api_key
     end
 
-    # Call prediction API on the document and parse the results.
+    # Call prediction API on a document and parse the results.
     #
-    # @param prediction_class [Mindee::Prediction::Prediction]
+    # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
     #
-    # @param endpoint_name [String] For custom endpoints, the "API name" field in the "Settings" page of the
-    #  API Builder. Do not set for standard (off the shelf) endpoints.
-    #
-    # @param account_name [String] For custom endpoints, your account or organization username on the API Builder.
-    #  This is normally not required unless you have a custom endpoint which has the same name as a
-    #  standard (off the shelf) endpoint.
-    #  Do not set for standard (off the shelf) endpoints.
+    # @param endpoint [HTTP::Endpoint] Endpoint of the API
+    # Doesn't need to be set in the case of OTS APIs.
     #
-    # @param include_words [Boolean] Whether to include the full text for each page.
+    # @param all_words [Boolean] Whether to include the full text for each page.
     #  This performs a full OCR operation on the server and will increase response time.
     #
     # @param close_file [Boolean] Whether to `close()` the file after parsing it.
@@ -44,170 +38,178 @@ module Mindee
     # @param cropper [Boolean] Whether to include cropper results for each page.
     #  This performs a cropping operation on the server and will increase response time.
     #
-    # @return [Mindee::DocumentResponse]
+    # @return [Mindee::Parsing::Common::ApiResponse]
     def parse(
-      prediction_class,
-      endpoint_name: '',
-      account_name: '',
-      include_words: false,
+      input_source,
+      product_class,
+      endpoint: nil,
+      all_words: false,
       close_file: true,
       page_options: nil,
       cropper: false
     )
-      doc_config = find_doc_config(prediction_class, endpoint_name, account_name)
-      @input_doc.process_pdf(page_options) if !page_options.nil? && @input_doc.pdf?
-      doc_config.predict(@input_doc, include_words, close_file, cropper)
-    end
-
-    private
-
-    # @param document_class [Mindee::Prediction::Prediction]
-    # @param endpoint_name [String]
-    def determine_endpoint_name(document_class, endpoint_name)
-      return document_class.name if document_class.name != Prediction::CustomV1.name
-
-      raise "endpoint_name is required when using #{document_class.name} class" if endpoint_name.empty?
-
-      endpoint_name
-    end
-
-    # @param document_class [Mindee::Prediction::Prediction]
-    # @param endpoint_name [String]
-    # @param account_name [String]
-    def find_doc_config(document_class, endpoint_name, account_name)
-      endpoint_name = determine_endpoint_name(document_class, endpoint_name)
-
-      found = []
-      @doc_configs.each_key do |conf|
-        found.push(conf) if conf[1] == endpoint_name
+      if input_source.is_a?(Mindee::Input::Source::LocalInputSource) && !page_options.nil? && input_source.pdf?
+        input_source.process_pdf(page_options)
       end
-      raise "Endpoint not configured: #{endpoint_name}" if found.empty?
-
-      if !account_name.empty?
-        config_key = [account_name, endpoint_name]
-      elsif found.length == 1
-        config_key = found[0]
-      else
-        usernames = found.map { |conf| conf[0] }
-        raise "Duplicate configuration detected.\n" \
-              "You specified the document '#{endpoint_name}' in your custom config.\n" \
-              "To avoid confusion, please add the 'account_name' attribute to " \
-              "the parse method, one of #{usernames}."
-      end
-
-      @doc_configs[config_key]
+      endpoint = initialize_endpoint(product_class) if endpoint.nil?
+      prediction = endpoint.predict(input_source, all_words, close_file, cropper)
+      Mindee::Parsing::Common::ApiResponse.new(product_class, prediction)
     end
-  end
 
-  # Mindee API Client.
-  # See: https://developers.mindee.com/docs/
-  class Client
-    # @param api_key [String]
-    def initialize(api_key: '')
-      @doc_configs = {}
-      @api_key = api_key
-      init_default_endpoints
+    # Enqueue a document for async parsing
+    #
+    # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
+    #
+    # @param endpoint [HTTP::Endpoint, nil] Endpoint of the API.
+    # Doesn't need to be set in the case of OTS APIs.
+    #
+    # @param all_words [Boolean] Whether to extract all the words on each page.
+    #  This performs a full OCR operation on the server and will increase response time.
+    #
+    # @param close_file [Boolean] Whether to `close()` the file after parsing it.
+    #  Set to false if you need to access the file after this operation.
+    #
+    # @param page_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.
+    #
+    # @param cropper [Boolean] Whether to include cropper results for each page.
+    #  This performs a cropping operation on the server and will increase response time.
+    #
+    # @return [Mindee::Parsing::Common::ApiResponse]
+    def enqueue(
+      input_source,
+      product_class,
+      endpoint: nil,
+      all_words: false,
+      close_file: true,
+      page_options: nil,
+      cropper: false
+    )
+      if input_source.is_a?(Mindee::Input::Source::LocalInputSource) && !page_options.nil? && input_source.pdf?
+        input_source.process_pdf(page_options)
+      end
+      endpoint = initialize_endpoint(product_class) if endpoint.nil?
+      Mindee::Parsing::Common::ApiResponse.new(product_class,
+                                               endpoint.predict_async(input_source, all_words, close_file, cropper))
     end
 
-    # Configure a custom document using the 'Mindee API Builder'.
-    # @param account_name [String] Your organization's username on the API Builder
-    # @param endpoint_name [String] The "API name" field in the "Settings" page of the API Builder
-    # @param version [String] Specify the version of the model to use. If not set, use the latest version of the model.
-    # @return [Mindee::Client]
-    def add_endpoint(
-      account_name,
-      endpoint_name,
-      version: '1'
+    # Parses a queued document
+    #
+    # @param endpoint [HTTP::Endpoint, nil] Endpoint of the API
+    # Doesn't need to be set in the case of OTS APIs.
+    #
+    # @param job_id [String] Id of the job (queue) to poll from
+    #
+    # @return [Mindee::Parsing::Common::ApiResponse]
+    def parse_queued(
+      job_id,
+      product_class,
+      endpoint: nil
     )
-      @doc_configs[[account_name, endpoint_name]] = DocumentConfig.new(
-        Prediction::CustomV1,
-        HTTP::CustomEndpoint.new(account_name, endpoint_name, version, @api_key)
-      )
-      self
+      endpoint = initialize_endpoint(product_class) if endpoint.nil?
+      Mindee::Parsing::Common::ApiResponse.new(product_class, endpoint.parse_async(job_id))
     end
 
     # Load a document from an absolute path, as a string.
     # @param input_path [String] Path of file to open
-    # @return [Mindee::DocumentClient]
-    def doc_from_path(input_path)
-      doc = Input::PathDocument.new(input_path)
-      DocumentClient.new(doc, @doc_configs)
+    # @return [Mindee::Input::Source::PathInputSource]
+    def source_from_path(input_path)
+      Input::Source::PathInputSource.new(input_path)
     end
 
     # Load a document from raw bytes.
     # @param input_bytes [String] Encoding::BINARY byte input
     # @param filename [String] The name of the file (without the path)
-    # @return [Mindee::DocumentClient]
-    def doc_from_bytes(input_bytes, filename)
-      doc = Input::BytesDocument.new(input_bytes, filename)
-      DocumentClient.new(doc, @doc_configs)
+    # @return [Mindee::Input::Source::BytesInputSource]
+    def source_from_bytes(input_bytes, filename)
+      Input::Source::BytesInputSource.new(input_bytes, filename)
     end
 
     # Load a document from a base64 encoded string.
     # @param base64_string [String] Input to parse as base64 string
     # @param filename [String] The name of the file (without the path)
-    # @return [Mindee::DocumentClient]
-    def doc_from_b64string(base64_string, filename)
-      doc = Input::Base64Document.new(base64_string, filename)
-      DocumentClient.new(doc, @doc_configs)
+    # @return [Mindee::Input::Source::Base64InputSource]
+    def source_from_b64string(base64_string, filename)
+      Input::Source::Base64InputSource.new(base64_string, filename)
     end
 
     # Load a document from a normal Ruby `File`.
     # @param input_file [File] Input file handle
     # @param filename [String] The name of the file (without the path)
-    # @return [Mindee::DocumentClient]
-    def doc_from_file(input_file, filename)
-      doc = Input::FileDocument.new(input_file, filename)
-      DocumentClient.new(doc, @doc_configs)
+    # @return [Mindee::Input::Source::FileInputSource]
+    def source_from_file(input_file, filename)
+      Input::Source::FileInputSource.new(input_file, filename)
+    end
+
+    # Load a document from a secure remote source (HTTPS).
+    # @param url [String] Url of the file
+    # @return [Mindee::Input::Source::UrlInputSource]
+    def source_from_url(url)
+      Input::Source::UrlInputSource.new(url)
+    end
+
+    # Creates a custom endpoint with the given values.
+    # Do not set for standard (off the shelf) endpoints.
+    #
+    # @param endpoint_name [String] For custom endpoints, the "API name" field in the "Settings" page of the
+    #  API Builder. Do not set for standard (off the shelf) endpoints.
+    #
+    # @param account_name [String] For custom endpoints, your account or organization username on the API Builder.
+    #  This is normally not required unless you have a custom endpoint which has the same name as a
+    #  standard (off the shelf) endpoint.
+    # @param version [String] For custom endpoints, version of the product
+    # @return [Mindee::HTTP::Endpoint]
+    def create_endpoint(endpoint_name: '', account_name: '', version: '')
+      initialize_endpoint(Mindee::Product::Custom::CustomV1, endpoint_name: endpoint_name, account_name: account_name,
+                                                             version: version)
     end
 
     private
 
-    def standard_document_config(prediction_class, endpoint_name, version)
-      DocumentConfig.new(
-        prediction_class,
-        HTTP::StandardEndpoint.new(endpoint_name, version, @api_key)
-      )
+    # Creates an endpoint with the given values. Raises an error if the endpoint is invalid.
+    # @param product_class [Mindee::Product] class of the product
+    #
+    # @param endpoint_name [String] For custom endpoints, the "API name" field in the "Settings" page of the
+    #  API Builder. Do not set for standard (off the shelf) endpoints.
+    #
+    # @param account_name [String] For custom endpoints, your account or organization username on the API Builder.
+    #  This is normally not required unless you have a custom endpoint which has the same name as a
+    #  standard (off the shelf) endpoint.
+    # @param version [String] For custom endpoints, version of the product.
+    # @return [Mindee::HTTP::Endpoint]
+    def initialize_endpoint(product_class, endpoint_name: '', account_name: '', version: '')
+      if (endpoint_name.nil? || endpoint_name.empty?) && product_class == Mindee::Product::Custom::CustomV1
+        raise 'Missing argument endpoint_name when using custom class'
+      end
+
+      endpoint_name = fix_endpoint_name(product_class, endpoint_name)
+      account_name = fix_account_name(account_name)
+      version = fix_version(product_class, version)
+      HTTP::Endpoint.new(account_name, endpoint_name, version, api_key: @api_key)
+    end
+
+    def fix_endpoint_name(product_class, endpoint_name)
+      return product_class.endpoint_name if endpoint_name.nil? || endpoint_name.empty?
+
+      endpoint_name
     end
 
-    def init_default_endpoints
-      @doc_configs[['mindee', Prediction::ProofOfAddressV1.name]] = standard_document_config(
-        Prediction::ProofOfAddressV1, 'proof_of_address', '1'
-      )
-      @doc_configs[['mindee', Prediction::FinancialDocumentV1.name]] = standard_document_config(
-        Prediction::FinancialDocumentV1, 'financial_document', '1'
-      )
-      @doc_configs[['mindee', Prediction::InvoiceV4.name]] = standard_document_config(
-        Prediction::InvoiceV4, 'invoices', '4'
-      )
-      @doc_configs[['mindee', Prediction::ReceiptV4.name]] = standard_document_config(
-        Prediction::ReceiptV4, 'expense_receipts', '4'
-      )
-      @doc_configs[['mindee', Prediction::ReceiptV5.name]] = standard_document_config(
-        Prediction::ReceiptV5, 'expense_receipts', '5'
-      )
-      @doc_configs[['mindee', Prediction::PassportV1.name]] = standard_document_config(
-        Prediction::PassportV1, 'passport', '1'
-      )
-      @doc_configs[['mindee', Prediction::EU::LicensePlateV1.name]] = standard_document_config(
-        Prediction::EU::LicensePlateV1, 'license_plates', '1'
-      )
-      @doc_configs[['mindee', Prediction::ShippingContainerV1.name]] = standard_document_config(
-        Prediction::ShippingContainerV1, 'shipping_containers', '1'
-      )
-      @doc_configs[['mindee', Prediction::US::BankCheckV1.name]] = standard_document_config(
-        Prediction::US::BankCheckV1, 'bank_check', '1'
-      )
-      @doc_configs[['mindee', Prediction::FR::BankAccountDetailsV1.name]] = standard_document_config(
-        Prediction::FR::BankAccountDetailsV1, 'bank_account_details', '1'
-      )
-      @doc_configs[['mindee', Prediction::FR::CarteVitaleV1.name]] = standard_document_config(
-        Prediction::FR::CarteVitaleV1, 'carte_vitale', '1'
-      )
-      @doc_configs[['mindee', Prediction::FR::IdCardV1.name]] = standard_document_config(
-        Prediction::FR::IdCardV1, 'idcard_fr', '1'
-      )
-      self
+    def fix_account_name(account_name)
+      return 'mindee' if account_name.nil? || account_name.empty?
+
+      account_name
+    end
+
+    def fix_version(product_class, version)
+      return version unless version.nil? || version.empty?
+      return '1' if product_class.endpoint_version.nil? || product_class.endpoint_version.empty?
+
+      product_class.endpoint_version
     end
   end
 end

data/lib/mindee/geometry/min_max.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Various helper functions & classes for geometry.
+  module Geometry
+    # A set of minimum and maximum values.
+    class MinMax
+      # Minimum
+      # @return [Float]
+      attr_reader :min
+      # Maximum
+      # @return [Float]
+      attr_reader :max
+
+      # @param min [Float]
+      # @param max [Float]
+      def initialize(min, max)
+        @min = min
+        @max = max
+      end
+    end
+  end
+end

data/lib/mindee/geometry/point.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Various helper functions for geometry.
+  module Geometry
+    # A relative set of coordinates (X, Y) on the document.
+    class Point
+      # @return [Float]
+      attr_accessor :x
+      # @return [Float]
+      attr_accessor :y
+
+      # @param x [Float]
+      # @param y [Float]
+      # rubocop:disable Naming/MethodParameterName
+      def initialize(x, y)
+        @x = x
+        @y = y
+      end
+      # rubocop:enable Naming/MethodParameterName
+
+      # @return [Float]
+      def [](key)
+        case key
+        when 0
+          @x
+        when 1
+          @y
+        else
+          throw '0 or 1 only'
+        end
+      end
+    end
+  end
+end

data/lib/mindee/geometry/polygon.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Various helper functions & classes for geometry.
+  module Geometry
+    # Contains any number of vertex coordinates (Points).
+    class Polygon < Array
+      # Get the central point (centroid) of the polygon.
+      # @return [Mindee::Geometry::Point]
+      def centroid
+        Geometry.get_centroid(self)
+      end
+
+      # Determine if the Point is in the Polygon's Y-axis.
+      # @param point [Mindee::Geometry::Point]
+      # @return [Boolean]
+      def point_in_y?(point)
+        min_max = Geometry.get_min_max_y(self)
+        min_max.min <= point.y && point.y <= min_max.max
+      end
+    end
+  end
+end

data/lib/mindee/geometry/quadrilateral.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Various helper functions & classes for geometry.
+  module Geometry
+    # Contains exactly 4 relative vertices coordinates (Points).
+    class Quadrilateral
+      # @return [Mindee::Geometry::Point]
+      attr_accessor :top_left
+      # @return [Mindee::Geometry::Point]
+      attr_accessor :top_right
+      # @return [Mindee::Geometry::Point]
+      attr_accessor :bottom_right
+      # @return [Mindee::Geometry::Point]
+      attr_accessor :bottom_left
+
+      # @param top_left [Mindee::Geometry::Point]
+      # @param top_right [Mindee::Geometry::Point]
+      # @param bottom_right [Mindee::Geometry::Point]
+      # @param bottom_left [Mindee::Geometry::Point]
+      def initialize(top_left, top_right, bottom_right, bottom_left)
+        @top_left = top_left
+        @top_right = top_right
+        @bottom_right = bottom_right
+        @bottom_left = bottom_left
+      end
+
+      # @return [Mindee::Geometry::Point]
+      def [](key)
+        case key
+        when 0
+          @top_left
+        when 1
+          @top_right
+        when 2
+          @bottom_right
+        when 3
+          @bottom_left
+        else
+          throw '0, 1, 2, 3 only'
+        end
+      end
+    end
+  end
+end

data/lib/mindee/geometry/utils.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Various helper functions for geometry.
+  module Geometry
+    # Transform a prediction into a Quadrilateral.
+    # @param prediction [Hash]
+    # @return [Mindee::Geometry::Quadrilateral]
+    def self.quadrilateral_from_prediction(prediction)
+      throw "Prediction must have exactly 4 points, found #{prediction.size}" if prediction.size != 4
+
+      Quadrilateral.new(
+        Point.new(prediction[0][0], prediction[0][1]),
+        Point.new(prediction[1][0], prediction[1][1]),
+        Point.new(prediction[2][0], prediction[2][1]),
+        Point.new(prediction[3][0], prediction[3][1])
+      )
+    end
+
+    # Transform a prediction into a Polygon.
+    # @param prediction [Hash]
+    # @return [Mindee::Geometry::Polygon]
+    def self.polygon_from_prediction(prediction)
+      polygon = Polygon.new
+      return polygon if prediction.nil?
+
+      prediction.each do |point|
+        polygon << Point.new(point[0], point[1])
+      end
+      polygon
+    end
+
+    # Gets the points of a bounding box for a given set of points
+    # @param vertices [Array<Mindee::Geometry::Point>]
+    # @return [Array<Float>]
+    def self.get_bbox(vertices)
+      x_coords = vertices.map(&:x)
+      y_coords = vertices.map(&:y)
+      [x_coords.min, y_coords.min, x_coords.max, y_coords.max]
+    end
+
+    # Creates the bounding bounding box for a given set of points
+    # @param vertices [Array<Mindee::Geometry::Point>]
+    # @return [Mindee::Geometry::Quadrilateral]
+    def self.get_bounding_box(vertices)
+      x_min, y_min, x_max, y_max = get_bbox(vertices)
+      Quadrilateral.new(
+        Point.new(x_min, y_min),
+        Point.new(x_max, y_min),
+        Point.new(x_max, y_max),
+        Point.new(x_min, y_max)
+      )
+    end
+
+    # Get the central point (centroid) given a sequence of points.
+    # @param points [Array<Mindee::Geometry::Point>]
+    # @return [Mindee::Geometry::Point]
+    def self.get_centroid(points)
+      vertices_count = points.size
+      x_sum = points.map(&:x).sum
+      y_sum = points.map(&:y).sum
+      Point.new(x_sum / vertices_count, y_sum / vertices_count)
+    end
+
+    # Get the maximum and minimum Y value given a sequence of points.
+    # @param points [Array<Mindee::Geometry::Point>]
+    # @return [Mindee::Geometry::MinMax]
+    def self.get_min_max_y(points)
+      coords = points.map(&:y)
+      MinMax.new(coords.min, coords.max)
+    end
+
+    # Get the maximum and minimum X value given a sequence of points.
+    # @param points [Array<Mindee::Geometry::Point>]
+    # @return [Mindee::Geometry::MinMax]
+    def self.get_min_max_x(points)
+      coords = points.map(&:x)
+      MinMax.new(coords.min, coords.max)
+    end
+  end
+end