mindee 1.2.0 → 2.1.0

data/lib/mindee/document_config.rb

@@ -2,199 +2,59 @@
 
 require 'json'
 
-require_relative 'endpoint'
-require_relative 'documents'
-require_relative 'response'
+require_relative 'http/endpoint'
+require_relative 'parsing/document'
+require_relative 'parsing/error'
+require_relative 'parsing/prediction'
 
 module Mindee
   # Specific client for sending a document to the API.
   class DocumentConfig
     # Array of possible Mindee::Endpoint to be used.
-    # @return [Array<Mindee::Endpoint>]
-    attr_reader :endpoints
+    # @return [Mindee::HTTP::Endpoint]
+    attr_reader :endpoint
 
-    # @param doc_class [Class<Mindee::Document>]
-    # @param document_type [String]
-    # @param endpoints [Array<Mindee::Endpoint>]
-    # @param raise_on_error [Boolean]
-    def initialize(doc_class, document_type, endpoints, raise_on_error)
-      @doc_class = doc_class
-      @document_type = document_type
-      @endpoints = endpoints
-      @raise_on_error = raise_on_error
-    end
-
-    # Parse a prediction API result.
-    # @param input_doc [Mindee::InputDocument]
-    # @param response [Hash]
-    # @return [Mindee::DocumentResponse]
-    def build_predict_result(input_doc, response)
-      document = @doc_class.new(
-        response['document']['inference']['prediction'],
-        input_file: input_doc,
-        page_id: nil
-      )
-      pages = []
-      response['document']['inference']['pages'].each do |page|
-        pages.push(
-          @doc_class.new(
-            page['prediction'],
-            input_file: input_doc,
-            page_id: page['id']
-          )
-        )
-      end
-      DocumentResponse.new(response, @document_type, document, pages)
+    # @param prediction_class [Class<Mindee::Prediction::Prediction>]
+    # @param endpoint [Mindee::HTTP::Endpoint]
+    def initialize(prediction_class, endpoint)
+      @prediction_class = prediction_class
+      @endpoint = endpoint
     end
 
     # Call the prediction API.
     # @param input_doc [Mindee::InputDocument]
     # @param include_words [Boolean]
     # @param close_file [Boolean]
+    # @param cropper [Boolean]
     # @return [Mindee::DocumentResponse]
-    def predict(input_doc, include_words, close_file)
-      check_api_keys
-      response = predict_request(input_doc, include_words, close_file)
-      parse_response(input_doc, response)
+    def predict(input_doc, include_words, close_file, cropper)
+      check_api_key
+      response = predict_request(input_doc, include_words, close_file, cropper)
+      hashed_response = JSON.parse(response.body, object_class: Hash)
+      return Document.new(@prediction_class, hashed_response['document']) if (200..299).include?(response.code.to_i)
+
+      error = Parsing::Error.new(hashed_response['api_request']['error'])
+      raise error
     end
 
     private
 
-    # @param input_doc [Mindee::InputDocument]
-    # @param response [Net::HTTPResponse]
-    # @return [Mindee::DocumentResponse]
-    def parse_response(input_doc, response)
-      hashed_response = JSON.parse(response.body, object_class: Hash)
-      unless (200..299).include?(response.code.to_i)
-        if @raise_on_error
-          raise Net::HTTPError.new(
-            "API #{response.code} HTTP error: #{hashed_response}", response
-          )
-        end
-        return DocumentResponse.new(
-          hashed_response, @document_type, {}, []
-        )
-      end
-      build_predict_result(input_doc, hashed_response)
-    end
-
     # @param input_doc [Mindee::InputDocument]
     # @param include_words [Boolean]
     # @param close_file [Boolean]
+    # # @param cropper [Boolean]
     # @return [Net::HTTPResponse]
-    def predict_request(input_doc, include_words, close_file)
-      @endpoints[0].predict_request(input_doc, include_words: include_words, close_file: close_file)
-    end
-
-    def check_api_keys
-      @endpoints.each do |endpoint|
-        next unless endpoint.api_key.nil? || endpoint.api_key.empty?
-
-        raise "Missing API key for '#{@document_type}', " \
-              "check your Client Configuration.\n" \
-              'You can set this using the ' \
-              "'#{endpoint.envvar_key_name}' environment variable."
-      end
-    end
-  end
-
-  # Client for Invoice documents
-  class InvoiceConfig < DocumentConfig
-    def initialize(api_key, raise_on_error)
-      endpoints = [InvoiceEndpoint.new(api_key)]
-      super(
-        Invoice,
-        'invoice',
-        endpoints,
-        raise_on_error
-      )
+    def predict_request(input_doc, include_words, close_file, cropper)
+      @endpoint.predict_req_post(input_doc, include_words: include_words, close_file: close_file, cropper: cropper)
     end
-  end
 
-  # Client for Receipt documents
-  class ReceiptConfig < DocumentConfig
-    def initialize(api_key, raise_on_error)
-      endpoints = [ReceiptEndpoint.new(api_key)]
-      super(
-        Receipt,
-        'receipt',
-        endpoints,
-        raise_on_error
-      )
-    end
-  end
+    def check_api_key
+      return unless @endpoint.api_key.nil? || @endpoint.api_key.empty?
 
-  # Client for Passport documents
-  class PassportConfig < DocumentConfig
-    def initialize(api_key, raise_on_error)
-      endpoints = [PassportEndpoint.new(api_key)]
-      super(
-        Passport,
-        'passport',
-        endpoints,
-        raise_on_error
-      )
-    end
-  end
-
-  # Client for Financial documents
-  class FinancialDocConfig < DocumentConfig
-    def initialize(api_key, raise_on_error)
-      endpoints = [
-        InvoiceEndpoint.new(api_key),
-        ReceiptEndpoint.new(api_key),
-      ]
-      super(
-        FinancialDocument,
-        'financial_doc',
-        endpoints,
-        raise_on_error
-      )
-    end
-
-    private
-
-    def predict_request(input_doc, include_words, close_file)
-      endpoint = input_doc.pdf? ? @endpoints[0] : @endpoints[1]
-      endpoint.predict_request(input_doc, include_words: include_words, close_file: close_file)
-    end
-  end
-
-  # Client for Custom (constructed) documents
-  class CustomDocConfig < DocumentConfig
-    def initialize(document_type, account_name, version, api_key, raise_on_error)
-      endpoints = [CustomEndpoint.new(document_type, account_name, version, api_key)]
-      super(
-        CustomDocument,
-        document_type,
-        endpoints,
-        raise_on_error
-      )
-    end
-
-    # Parse a prediction API result.
-    # @param input_doc [Mindee::InputDocument]
-    # @param response [Hash]
-    # @return [Mindee::DocumentResponse]
-    def build_predict_result(input_doc, response)
-      document = CustomDocument.new(
-        @document_type,
-        response['document']['inference']['prediction'],
-        input_file: input_doc,
-        page_id: nil
-      )
-      pages = []
-      response['document']['inference']['pages'].each do |page|
-        pages.push(
-          CustomDocument.new(
-            @document_type,
-            page['prediction'],
-            input_file: input_doc,
-            page_id: page['id']
-          )
-        )
-      end
-      DocumentResponse.new(response, @document_type, document, pages)
+      raise "Missing API key for '#{@document_type}', " \
+            "check your Client Configuration.\n" \
+            'You can set this using the ' \
+            "'#{HTTP::API_KEY_ENV_NAME}' environment variable."
     end
   end
 end

data/lib/mindee/geometry.rb

@@ -3,19 +3,116 @@
 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
+
+    # 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
+
+    class Polygon < Array
+    end
+
+    # Transform a prediction into a 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.
+    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
+
     # @return [Array<Float>]
     def self.get_bbox(vertices)
-      x_min = vertices.map { |v| v[0] }.min
-      x_max = vertices.map { |v| v[0] }.max
-      y_min = vertices.map { |v| v[1] }.min
-      y_max = vertices.map { |v| v[1] }.max
-      [x_min, y_min, x_max, y_max]
+      x_coords = vertices.map(&:x)
+      y_coords = vertices.map(&:y)
+      [x_coords.min, y_coords.min, x_coords.max, y_coords.max]
     end
 
-    # @return [Array<Array<Float>>]
-    def self.get_bbox_as_polygon(vertices)
+    # @return [Mindee::Geometry::Quadrilateral]
+    def self.get_bounding_box(vertices)
       x_min, y_min, x_max, y_max = get_bbox(vertices)
-      [[x_min, y_min], [x_max, y_min], [x_max, y_max], [x_min, y_max]]
+      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
   end
 end

data/lib/mindee/http/endpoint.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require_relative '../version'
+
+module Mindee
+  module HTTP
+    API_KEY_ENV_NAME = 'MINDEE_API_KEY'
+    API_KEY_DEFAULT = nil
+
+    BASE_URL_ENV_NAME = 'MINDEE_BASE_URL'
+    BASE_URL_DEFAULT = 'https://api.mindee.net/v1'
+
+    REQUEST_TIMEOUT_ENV_NAME = 'MINDEE_REQUEST_TIMEOUT'
+    TIMEOUT_DEFAULT = 120
+
+    USER_AGENT = "mindee-api-ruby@v#{Mindee::VERSION} ruby-v#{RUBY_VERSION} #{Mindee::PLATFORM}"
+
+    # Generic API endpoint for a product.
+    class Endpoint
+      # @return [String]
+      attr_reader :api_key
+      # @return [Integer]
+      attr_reader :request_timeout
+
+      def initialize(owner, url_name, version, api_key: '')
+        @owner = owner
+        @url_name = url_name
+        @version = version
+        @request_timeout = ENV.fetch(REQUEST_TIMEOUT_ENV_NAME, TIMEOUT_DEFAULT).to_i
+        @api_key = api_key.nil? || api_key.empty? ? ENV.fetch(API_KEY_ENV_NAME, API_KEY_DEFAULT) : api_key
+        @url_root = "#{BASE_URL_DEFAULT}/products/#{@owner}/#{@url_name}/v#{@version}"
+      end
+
+      # @param input_doc [Mindee::InputDocument]
+      # @param include_words [Boolean]
+      # @param close_file [Boolean]
+      # @param cropper [Boolean]
+      # @return [Net::HTTPResponse]
+      def predict_req_post(input_doc, include_words: false, close_file: true, cropper: false)
+        uri = URI("#{@url_root}/predict")
+
+        params = {}
+        params[:cropper] = 'true' if cropper
+        uri.query = URI.encode_www_form(params)
+
+        headers = {
+          'Authorization' => "Token #{@api_key}",
+          'User-Agent' => USER_AGENT,
+        }
+        req = Net::HTTP::Post.new(uri, headers)
+
+        form_data = {
+          'document' => input_doc.read_document(close: close_file),
+        }
+        form_data.push ['include_mvision', 'true'] if include_words
+
+        req.set_form(form_data, 'multipart/form-data')
+
+        Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|
+          http.request(req)
+        end
+      end
+    end
+
+    # Receipt API endpoint
+    class StandardEndpoint < Endpoint
+      def initialize(endpoint_name, version, api_key)
+        super('mindee', endpoint_name, version, api_key: api_key)
+      end
+    end
+
+    # Custom (constructed) API endpoint
+    class CustomEndpoint < Endpoint
+      def initialize(account_name, endpoint_name, version, api_key)
+        super(account_name, endpoint_name, version, api_key: api_key)
+      end
+    end
+  end
+end

data/lib/mindee/input/pdf_processing.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'origami'
+
+# Monkey-patching for Origami
+module PDFTools
+  def to_io_stream(params = {})
+    options = {
+      delinearize: true,
+      recompile: true,
+      decrypt: false,
+    }
+    options.update(params)
+
+    if frozen? # incompatible flags with frozen doc (signed)
+      options[:recompile] = nil
+      options[:rebuild_xrefs] = nil
+      options[:noindent] = nil
+      options[:obfuscate] = false
+    end
+    load_all_objects unless @loaded
+
+    intents_as_pdfa1 if options[:intent] =~ %r{pdf[/-]?A1?/i}
+    delinearize! if options[:delinearize] && linearized?
+    compile(options) if options[:recompile]
+
+    io_stream = StringIO.new(output(options))
+    io_stream.set_encoding Encoding::BINARY
+    io_stream
+  end
+end
+
+Origami::PDF.class_eval { include PDFTools }
+
+module Mindee
+  module Input
+    # Class for PDF documents
+    module PdfProcessor
+      DEFAULT_OPTIONS = {
+        page_indexes: [0],
+        operation: :KEEP_ONLY,
+        on_min_pages: 0,
+      }.freeze
+
+      # @param io_stream [StreamIO]
+      # @param options [Hash]
+      def self.parse(io_stream, options)
+        options = DEFAULT_OPTIONS.merge(options)
+
+        current_pdf = open_pdf(io_stream)
+        pages_count = current_pdf.pages.size
+        return if options[:on_min_pages] > pages_count
+
+        all_pages = (0..pages_count - 1).to_a
+
+        case options[:operation]
+        when :KEEP_ONLY
+          pages_to_remove = indexes_from_keep(options[:page_indexes], all_pages)
+        when :REMOVE
+          pages_to_remove = indexes_from_remove(options[:page_indexes], all_pages)
+        else
+          raise "operation must be one of :KEEP_ONLY or :REMOVE, sent '#{behavior}'"
+        end
+
+        current_pdf.delete_pages_at(pages_to_remove) if pages_to_remove.to_a != all_pages.to_a
+        current_pdf.to_io_stream
+      end
+
+      # @param page_indexes [Array]
+      # @param all_pages [Array]
+      def self.indexes_from_keep(page_indexes, all_pages)
+        pages_to_keep = Set.new
+        page_indexes.each do |idx|
+          idx = (all_pages.length - (idx + 2)) if idx.negative?
+          page = all_pages[idx]
+          next if page.nil?
+
+          pages_to_keep << page
+        end
+        all_pages.to_set - pages_to_keep
+      end
+
+      # @param page_indexes [Array]
+      # @param all_pages [Array]
+      def self.indexes_from_remove(page_indexes, all_pages)
+        pages_to_remove = Set.new
+        page_indexes.each do |idx|
+          idx = (all_pages.length - (idx + 2)) if idx.negative?
+          page = all_pages[idx]
+          next if page.nil?
+
+          pages_to_remove << page
+        end
+      end
+
+      # @param io_stream [StringIO]
+      # @return [Origami::PDF]
+      def self.open_pdf(io_stream)
+        pdf_parser = Origami::PDF::LinearParser.new({ verbosity: Origami::Parser::VERBOSE_QUIET })
+        io_stream.seek(0)
+        pdf_parser.parse(io_stream)
+      end
+    end
+  end
+end

data/lib/mindee/input/sources.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require 'marcel'
+
+require_relative 'pdf_processing'
+
+module Mindee
+  module Input
+    ALLOWED_MIME_TYPES = [
+      'application/pdf',
+      'image/heic',
+      'image/png',
+      'image/jpeg',
+      'image/tiff',
+      'image/webp',
+    ].freeze
+
+    # Base class for loading documents.
+    class InputDocument
+      # @return [String]
+      attr_reader :filename
+      # @return [String]
+      attr_reader :file_mimetype
+      # @return [StreamIO]
+      attr_reader :io_stream
+
+      # @param io_stream [StreamIO]
+      def initialize(io_stream, filename)
+        @io_stream = io_stream
+        @filename = filename
+        @file_mimetype = Marcel::MimeType.for @io_stream, name: @filename
+
+        return if ALLOWED_MIME_TYPES.include? @file_mimetype
+
+        raise "File type not allowed, must be one of #{ALLOWED_MIME_TYPES.join(', ')}"
+      end
+
+      def pdf?
+        @file_mimetype == 'application/pdf'
+      end
+
+      def process_pdf(options)
+        @io_stream.seek(0)
+        @io_stream = PdfProcessor.parse(@io_stream, options)
+      end
+
+      # @param close [Boolean]
+      def read_document(close: true)
+        @io_stream.seek(0)
+        data = @io_stream.read
+        @io_stream.close if close
+        [data].pack('m')
+      end
+    end
+
+    # Load a document from a path.
+    class PathDocument < InputDocument
+      # @param filepath [String]
+      def initialize(filepath)
+        io_stream = File.open(filepath, 'rb')
+        super(io_stream, File.basename(filepath))
+      end
+    end
+
+    # Load a document from a base64 string.
+    class Base64Document < InputDocument
+      # @param base64_string [String]
+      # @param filename [String]
+      def initialize(base64_string, filename)
+        io_stream = StringIO.new(base64_string.unpack1('m*'))
+        io_stream.set_encoding Encoding::BINARY
+        super(io_stream, filename)
+      end
+    end
+
+    # Load a document from raw bytes.
+    class BytesDocument < InputDocument
+      # @param raw_bytes [String]
+      # @param filename [String]
+      def initialize(raw_bytes, filename)
+        io_stream = StringIO.new(raw_bytes)
+        io_stream.set_encoding Encoding::BINARY
+        super(io_stream, filename)
+      end
+    end
+
+    # Load a document from a file handle.
+    class FileDocument < InputDocument
+      # @param filename [String]
+      def initialize(file_handle, filename)
+        io_stream = file_handle
+        super(io_stream, filename)
+      end
+    end
+  end
+end

data/lib/mindee/input.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'input/sources'

data/lib/mindee/parsing/document.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'inference'
+
+module Mindee
+  # Stores all response attributes.
+  class Document
+    # @return [Mindee::Inference]
+    attr_reader :inference
+    # @return [String] Filename sent to the API
+    attr_reader :name
+    # @return [String] Mindee ID of the document
+    attr_reader :id
+
+    # @param prediction_class [Class<Mindee::Prediction::Prediction>]
+    # @param http_response [Hash]
+    def initialize(prediction_class, http_response)
+      @id = http_response['id']
+      @name = http_response['name']
+      @inference = Mindee::Inference.new(prediction_class, http_response['inference'])
+    end
+
+    def to_s
+      out_str = String.new
+      out_str << "########\nDocument\n########"
+      out_str << "\n:Mindee ID: #{@id}"
+      out_str << "\n:Filename: #{@name}"
+      out_str << "\n\n#{@inference}"
+    end
+  end
+end

data/lib/mindee/parsing/error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    # API Error
+    class Error < StandardError
+      # @return [String]
+      attr_reader :api_code
+      # @return [String]
+      attr_reader :api_details
+      # @return [String]
+      attr_reader :api_message
+
+      def initialize(error)
+        @api_code = error['code']
+        @api_details = error['details']
+        @api_message = error['message']
+        super("#{@api_code}: #{@api_details} - #{@api_message}")
+      end
+    end
+  end
+end