mindee 1.0.0

data/lib/mindee/documents/invoice.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require_relative '../fields'
+require_relative 'base'
+
+module Mindee
+  # Invoice document.
+  class Invoice < Document
+    # @return [Mindee::Locale]
+    attr_reader :locale
+    # @return [Mindee::Amount]
+    attr_reader :total_incl
+    # @return [Mindee::Amount]
+    attr_reader :total_excl
+    # @return [Mindee::Amount]
+    attr_reader :total_tax
+    # @return [Mindee::DateField]
+    attr_reader :date
+    # @return [Mindee::Field]
+    attr_reader :invoice_number
+    # @return [Mindee::DateField]
+    attr_reader :due_date
+    # @return [Array<Mindee::TaxField>]
+    attr_reader :taxes
+    # @return [Array<Mindee::CompanyRegistration>]
+    attr_reader :customer_company_registration
+    # @return [Array<Mindee::PaymentDetails>]
+    attr_reader :payment_details
+    # @return [Array<Mindee::CompanyRegistration>]
+    attr_reader :company_registration
+    # @return [Mindee::Field]
+    attr_reader :customer_name
+    # @return [Mindee::Field]
+    attr_reader :supplier
+    # @return [Mindee::Field]
+    attr_reader :supplier_address
+    # @return [Mindee::Field]
+    attr_reader :customer_address
+    # @return [Mindee::Orientation]
+    attr_reader :orientation
+
+    # @param prediction [Hash]
+    # @param input_file [Mindee::InputDocument, nil]
+    # @param page_id [Integer, nil]
+    def initialize(prediction, input_file: nil, page_id: nil)
+      super('invoice', input_file: input_file)
+      @orientation = Orientation.new(prediction['orientation'], page_id) if page_id
+      @locale = Locale.new(prediction['locale'])
+      @total_incl = Amount.new(prediction['total_incl'], page_id)
+      @total_excl = Amount.new(prediction['total_excl'], page_id)
+      @customer_address = Field.new(prediction['customer_address'], page_id)
+      @customer_name = Field.new(prediction['customer'], page_id)
+      @date = DateField.new(prediction['date'], page_id)
+      @due_date = DateField.new(prediction['due_date'], page_id)
+      @invoice_number = Field.new(prediction['invoice_number'], page_id)
+      @supplier = Field.new(prediction['supplier'], page_id)
+      @supplier_address = Field.new(prediction['supplier_address'], page_id)
+
+      @customer_company_registration = []
+      prediction['customer_company_registration'].each do |item|
+        @customer_company_registration.push(CompanyRegistration.new(item, page_id))
+      end
+      @taxes = []
+      prediction['taxes'].each do |item|
+        @taxes.push(TaxField.new(item, page_id))
+      end
+      @payment_details = []
+      prediction['payment_details'].each do |item|
+        @payment_details.push(PaymentDetails.new(item, page_id))
+      end
+      @company_registration = []
+      prediction['company_registration'].each do |item|
+        @company_registration.push(CompanyRegistration.new(item, page_id))
+      end
+
+      @total_tax = Amount.new(
+        { value: nil, confidence: 0.0 }, page_id
+      )
+      reconstruct(page_id)
+    end
+
+    def to_s
+      customer_company_registration = @customer_company_registration.map(&:value).join('; ')
+      payment_details = @payment_details.map(&:to_s).join("\n                 ")
+      company_registration = @company_registration.map(&:to_s).join('; ')
+      taxes = @taxes.join("\n       ")
+      out_str = String.new
+      out_str << '-----Invoice data-----'
+      out_str << "\nFilename: #{@filename}".rstrip
+      out_str << "\nInvoice number: #{@invoice_number}".rstrip
+      out_str << "\nTotal amount including taxes: #{@total_incl}".rstrip
+      out_str << "\nTotal amount excluding taxes: #{@total_excl}".rstrip
+      out_str << "\nInvoice date: #{@date}".rstrip
+      out_str << "\nInvoice due date: #{@due_date}".rstrip
+      out_str << "\nSupplier name: #{@supplier}".rstrip
+      out_str << "\nSupplier address: #{@supplier_address}".rstrip
+      out_str << "\nCustomer name: #{@customer_name}".rstrip
+      out_str << "\nCustomer company registration: #{customer_company_registration}".rstrip
+      out_str << "\nCustomer address: #{@customer_address}".rstrip
+      out_str << "\nPayment details: #{payment_details}".rstrip
+      out_str << "\nCompany numbers: #{company_registration}".rstrip
+      out_str << "\nTaxes: #{taxes}".rstrip
+      out_str << "\nTotal taxes: #{@total_tax}".rstrip
+      out_str << "\nLocale: #{@locale}".rstrip
+      out_str << "\n----------------------"
+      out_str
+    end
+
+    private
+
+    def reconstruct(page_id)
+      construct_total_tax_from_taxes(page_id)
+      construct_total_excl_from_tcc_and_taxes(page_id)
+      construct_total_incl_from_taxes_plus_excl(page_id)
+      construct_total_tax_from_totals(page_id)
+    end
+
+    def construct_total_excl_from_tcc_and_taxes(page_id)
+      return if @total_incl.value.nil? || taxes.empty? || !@total_excl.value.nil?
+
+      total_excl = {
+        'value' => @total_incl.value - @taxes.map(&:value).sum,
+        'confidence' => Field.array_confidence(@taxes) * @total_incl.confidence,
+      }
+      @total_excl = Amount.new(total_excl, page_id, reconstructed: true)
+    end
+
+    def construct_total_incl_from_taxes_plus_excl(page_id)
+      return if @total_excl.value.nil? || @taxes.empty? || !@total_incl.value.nil?
+
+      total_incl = {
+        'value' => @taxes.map(&:value).sum + @total_excl.value,
+        'confidence' => Field.array_confidence(@taxes) * @total_excl.confidence,
+      }
+      @total_incl = Amount.new(total_incl, page_id, reconstructed: true)
+    end
+
+    def construct_total_tax_from_taxes(page_id)
+      return if @taxes.empty?
+
+      total_tax = {
+        'value' => @taxes.map(&:value).sum,
+        'confidence' => Field.array_confidence(@taxes),
+      }
+      return unless total_tax['value'].positive?
+
+      @total_tax = Amount.new(total_tax, page_id, reconstructed: true)
+    end
+
+    def construct_total_tax_from_totals(page_id)
+      return if !@total_tax.value.nil? || @total_incl.value.nil? || @total_excl.value.nil?
+
+      total_tax = {
+        'value' => @total_incl.value - @total_excl.value,
+        'confidence' => Field.array_confidence(@taxes),
+      }
+      return unless total_tax['value'] >= 0
+
+      @total_tax = Amount.new(total_tax, page_id, reconstructed: true)
+    end
+  end
+end

data/lib/mindee/documents/passport.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'mrz'
+
+require_relative '../fields'
+require_relative 'base'
+
+# We need to do this disgusting thing to avoid the following error message:
+# td3 line one does not match the required format (MRZ::InvalidFormatError)
+#
+# See:
+# https://github.com/streetspotr/mrz/issues/2
+# https://github.com/streetspotr/mrz/pull/3
+#
+MRZ::TD3Parser::FORMAT_ONE = %r{\A(.{2})(.{3})([^<]+)<(.*)\z}.freeze
+
+module Mindee
+  # Passport document.
+  class Passport < Document
+    # @return [Mindee::Orientation]
+    attr_reader :orientation
+    attr_reader :country,
+                :id_number,
+                :expiry_date,
+                :issuance_date,
+                :surname,
+                :given_names,
+                :full_name,
+                :birth_date,
+                :birth_place,
+                :gender,
+                :mrz1,
+                :mrz2,
+                :mrz
+
+    # @param prediction [Hash]
+    # @param input_file [Mindee::InputDocument, nil]
+    # @param page_id [Integer, nil]
+    def initialize(prediction, input_file: nil, page_id: nil)
+      super('passport', input_file: input_file)
+      @orientation = Orientation.new(prediction['orientation'], page_id) if page_id
+      @country = Field.new(prediction['country'], page_id)
+      @id_number = Field.new(prediction['id_number'], page_id)
+      @birth_date = DateField.new(prediction['birth_date'], page_id)
+      @expiry_date = DateField.new(prediction['expiry_date'], page_id)
+      @issuance_date = DateField.new(prediction['issuance_date'], page_id)
+      @birth_place = Field.new(prediction['birth_place'], page_id)
+      @gender = Field.new(prediction['gender'], page_id)
+      @surname = Field.new(prediction['surname'], page_id)
+      @mrz1 = Field.new(prediction['mrz1'], page_id)
+      @mrz2 = Field.new(prediction['mrz2'], page_id)
+      @given_names = []
+      prediction['given_names'].each do |item|
+        @given_names.push(Field.new(item, page_id))
+      end
+      @full_name = construct_full_name(page_id)
+      @mrz = construct_mrz(page_id)
+      check_mrz
+    end
+
+    def to_s
+      given_names = @given_names.join(' ')
+      out_str = String.new
+      out_str << '-----Passport data-----'
+      out_str << "\nFilename: #{@filename}".rstrip
+      out_str << "\nFull name: #{@full_name}".rstrip
+      out_str << "\nGiven names: #{given_names}".rstrip
+      out_str << "\nSurname: #{@surname}".rstrip
+      out_str << "\nCountry: #{@country}".rstrip
+      out_str << "\nID Number: #{@id_number}".rstrip
+      out_str << "\nIssuance date: #{@issuance_date}".rstrip
+      out_str << "\nBirth date: #{@birth_date}".rstrip
+      out_str << "\nExpiry date: #{@expiry_date}".rstrip
+      out_str << "\nMRZ 1: #{@mrz1}".rstrip
+      out_str << "\nMRZ 2: #{@mrz2}".rstrip
+      out_str << "\nMRZ: #{@mrz}".rstrip
+      out_str << "\n----------------------"
+      out_str
+    end
+
+    # @return [Boolean]
+    def expired?
+      return true unless @expiry_date.date_object
+
+      @expiry_date.date_object < Date.today
+    end
+
+    private
+
+    def check_mrz
+      return if @mrz1.value.nil? || @mrz2.value.nil?
+
+      mrz = MRZ.parse([@mrz1.value, @mrz2.value])
+      checks = {
+        mrz_valid: valid_mrz?(mrz),
+        mrz_valid_birth_date: valid_birth_date?(mrz),
+        mrz_valid_expiry_date: valid_expiry_date?(mrz),
+        mrz_valid_id_number: valid_id_number?(mrz),
+        mrz_valid_surname: valid_surname?(mrz),
+        mrz_valid_country: valid_country?(mrz),
+      }
+      @checklist.merge!(checks)
+    end
+
+    def valid_mrz?(mrz)
+      check = mrz.valid?
+      @mrz.confidence = 1.0 if check
+      check
+    end
+
+    def valid_birth_date?(mrz)
+      check = mrz.valid_birth_date? && mrz.birth_date == @birth_date.date_object
+      @birth_date.confidence = 1.0 if check
+      check
+    end
+
+    def valid_expiry_date?(mrz)
+      check = mrz.valid_expiration_date? && mrz.expiration_date == @expiry_date.date_object
+      @expiry_date.confidence = 1.0 if check
+      check
+    end
+
+    def valid_id_number?(mrz)
+      check = mrz.valid_document_number? && mrz.document_number == @id_number.value
+      @id_number.confidence = 1.0 if check
+      check
+    end
+
+    def valid_surname?(mrz)
+      check = mrz.last_name == @surname.value
+      @surname.confidence = 1.0 if check
+      check
+    end
+
+    def valid_country?(mrz)
+      check = mrz.nationality == @country.value
+      @country.confidence = 1.0 if check
+      check
+    end
+
+    def construct_full_name(page_id)
+      return unless @surname.value &&
+                    !@given_names.empty? &&
+                    @given_names[0].value
+
+      full_name = {
+        'value' => "#{@given_names[0].value} #{@surname.value}",
+        'confidence' => Field.array_confidence([@surname, @given_names[0]]),
+      }
+      Field.new(full_name, page_id, reconstructed: true)
+    end
+
+    def construct_mrz(page_id)
+      return if @mrz1.value.nil? || @mrz2.value.nil?
+
+      mrz = {
+        'value' => @mrz1.value + @mrz2.value,
+        'confidence' => Field.array_confidence([@mrz1, @mrz2]),
+      }
+      Field.new(mrz, page_id, reconstructed: true)
+    end
+  end
+end

data/lib/mindee/documents/receipt.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative '../fields'
+require_relative 'base'
+
+module Mindee
+  # Receipt document.
+  class Receipt < Document
+    # @return [Mindee::Locale]
+    attr_reader :locale
+    # @return [Mindee::Amount]
+    attr_reader :total_incl
+    # @return [Mindee::Amount]
+    attr_reader :total_excl
+    # @return [Mindee::Amount]
+    attr_reader :total_tax
+    # @return [Mindee::DateField]
+    attr_reader :date
+    # @return [Mindee::Field]
+    attr_reader :supplier
+    # @return [Array<Mindee::TaxField>]
+    attr_reader :taxes
+    # @return [Mindee::Orientation]
+    attr_reader :orientation
+    # @return [Mindee::Field]
+    attr_reader :time
+    # @return [Mindee::Field]
+    attr_reader :category
+
+    # @param prediction [Hash]
+    # @param input_file [Mindee::InputDocument, nil]
+    # @param page_id [Integer, nil]
+    def initialize(prediction, input_file: nil, page_id: nil)
+      super('receipt', input_file: input_file)
+      @orientation = Orientation.new(prediction['orientation'], page_id) if page_id
+      @locale = Locale.new(prediction['locale'])
+      @total_incl = Amount.new(prediction['total_incl'], page_id)
+      @date = DateField.new(prediction['date'], page_id)
+      @category = Field.new(prediction['category'], page_id)
+      @supplier = Field.new(prediction['supplier'], page_id)
+      @time = Field.new(prediction['time'], page_id)
+      @taxes = []
+      prediction['taxes'].each do |item|
+        @taxes.push(TaxField.new(item, page_id))
+      end
+
+      @total_tax = Amount.new(
+        { value: nil, confidence: 0.0 }, page_id
+      )
+      @total_excl = Amount.new(
+        { value: nil, confidence: 0.0 }, page_id
+      )
+      reconstruct(page_id)
+    end
+
+    def to_s
+      taxes = @taxes.join("\n       ")
+      out_str = String.new
+      out_str << '-----Receipt data-----'
+      out_str << "\nFilename: #{@filename}".rstrip
+      out_str << "\nTotal amount including taxes: #{@total_incl}".rstrip
+      out_str << "\nTotal amount excluding taxes: #{@total_excl}".rstrip
+      out_str << "\nDate: #{@date}".rstrip
+      out_str << "\nCategory: #{@category}".rstrip
+      out_str << "\nTime: #{@time}".rstrip
+      out_str << "\nMerchant name: #{@supplier}".rstrip
+      out_str << "\nTaxes: #{taxes}".rstrip
+      out_str << "\nTotal taxes: #{@total_tax}".rstrip
+      out_str << "\nLocale: #{@locale}".rstrip
+      out_str << "\n----------------------"
+      out_str
+    end
+
+    private
+
+    def reconstruct(page_id)
+      construct_total_tax_from_taxes(page_id)
+      construct_total_excl(page_id)
+    end
+
+    def construct_total_tax_from_taxes(page_id)
+      return if @taxes.empty? || !@total_tax.value.nil?
+
+      total_tax = {
+        'value' => @taxes.map do |tax|
+          if tax.value.nil?
+            0
+          else
+            tax.value
+          end
+        end.sum,
+        'confidence' => Field.array_confidence(@taxes),
+      }
+      return unless total_tax['value'].positive?
+
+      @total_tax = Amount.new(total_tax, page_id, reconstructed: true)
+    end
+
+    def construct_total_excl(page_id)
+      return if @taxes.empty? || @total_incl.value.nil?
+
+      total_excl = {
+        'value' => @total_incl.value - Field.array_sum(@taxes),
+        'confidence' => Field.array_confidence(@taxes) * @total_incl.confidence,
+      }
+      @total_excl = Amount.new(total_excl, page_id, reconstructed: true)
+    end
+  end
+end

data/lib/mindee/documents.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'documents/invoice'
+require_relative 'documents/receipt'
+require_relative 'documents/passport'
+require_relative 'documents/financial_doc'
+require_relative 'documents/custom'

data/lib/mindee/endpoint.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require_relative 'version'
+
+module Mindee
+  MINDEE_API_URL = 'https://api.mindee.net/v1'
+  USER_AGENT = "mindee-api-ruby@v#{Mindee::VERSION} ruby-v#{RUBY_VERSION} #{Mindee::PLATFORM}"
+
+  INVOICE_VERSION = '3'
+  INVOICE_URL_NAME = 'invoices'
+
+  RECEIPT_VERSION = '3'
+  RECEIPT_URL_NAME = 'expense_receipts'
+
+  PASSPORT_VERSION = '1'
+  PASSPORT_URL_NAME = 'passport'
+
+  # Generic API endpoint for a product.
+  class Endpoint
+    attr_reader :api_key
+
+    def initialize(owner, url_name, version, key_name: nil, api_key: nil)
+      @owner = owner
+      @url_name = url_name
+      @version = version
+      @key_name = key_name || url_name
+      @api_key = api_key || set_api_key_from_env
+      @url_root = "#{MINDEE_API_URL}/products/#{@owner}/#{@url_name}/v#{@version}"
+    end
+
+    # @param input_doc [Mindee::InputDocument]
+    # @param include_words [Boolean]
+    # @param close_file [Boolean]
+    # @return [Net::HTTPResponse]
+    def predict_request(input_doc, include_words: false, close_file: true)
+      uri = URI("#{@url_root}/predict")
+      headers = {
+        'Authorization' => "Token #{@api_key}",
+        'User-Agent' => USER_AGENT,
+      }
+      req = Net::HTTP::Post.new(uri, headers)
+
+      params = {
+        'document' => input_doc.read_document(close: close_file),
+      }
+      params.push ['include_mvision', 'true'] if include_words
+
+      req.set_form(params, 'multipart/form-data')
+
+      Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+        http.request(req)
+      end
+    end
+
+    def envvar_key_name
+      key_name = to_envar(@key_name)
+      key_name = "#{to_envar(@owner)}_#{key_name}" if @owner != 'mindee'
+      "MINDEE_#{key_name}_API_KEY"
+    end
+
+    private
+
+    # Create a standard way to get/set environment variable names.
+    def to_envar(name)
+      name.sub('-', '_').upcase
+    end
+
+    # Set the endpoint's API key from an environment variable, if present.
+    # We look first for the specific key, if not set, we'll use the generic key
+    def set_api_key_from_env
+      env_key = ENV.fetch(envvar_key_name, nil)
+      env_key = ENV.fetch('MINDEE_API_KEY', nil) if env_key.nil?
+      @api_key = env_key if env_key
+    end
+  end
+
+  # Invoice API endpoint
+  class InvoiceEndpoint < Endpoint
+    def initialize(api_key)
+      super('mindee', INVOICE_URL_NAME, INVOICE_VERSION, key_name: 'invoice', api_key: api_key)
+    end
+  end
+
+  # Receipt API endpoint
+  class ReceiptEndpoint < Endpoint
+    def initialize(api_key)
+      super('mindee', RECEIPT_URL_NAME, RECEIPT_VERSION, key_name: 'receipt', api_key: api_key)
+    end
+  end
+
+  # Passport API endpoint
+  class PassportEndpoint < Endpoint
+    def initialize(api_key)
+      super('mindee', PASSPORT_URL_NAME, PASSPORT_VERSION, api_key: api_key)
+    end
+  end
+
+  # Custom (constructed) API endpoint
+  class CustomEndpoint < Endpoint
+    def initialize(document_type, account_name, version, api_key)
+      super(account_name, document_type, version, api_key: api_key)
+    end
+  end
+end

data/lib/mindee/fields/amount.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Mindee
+  # Represents tax information.
+  class Amount < Field
+    # Amount value as 3 decimal float
+    # @return [Float, nil]
+    attr_reader :value
+
+    def initialize(prediction, page_id, reconstructed: false)
+      super
+      @value = @value.round(3) unless @value.nil?
+    end
+  end
+end

data/lib/mindee/fields/base.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative '../geometry'
+
+module Mindee
+  # Base field object.
+  class Field
+    # @return [String, Float, Integer, Boolean]
+    attr_reader :value
+    # @return [Array<Array<Float>>]
+    attr_reader :bbox
+    # @return [Array<Array<Float>>]
+    attr_reader :polygon
+    # @return [Integer, nil]
+    attr_reader :page_id
+    # true if the field was reconstructed or computed using other fields.
+    # @return [Boolean]
+    attr_reader :reconstructed
+    # The confidence score, value will be between 0.0 and 1.0
+    # @return [Float]
+    attr_accessor :confidence
+
+    # @param prediction [Hash]
+    # @param page_id [Integer, nil]
+    # @param reconstructed [Boolean]
+    def initialize(prediction, page_id, reconstructed: false)
+      @value = prediction['value']
+      @confidence = prediction['confidence']
+      @polygon = prediction['polygon']
+      @bbox = Geometry.get_bbox_as_polygon(@polygon) unless @polygon.nil? || @polygon.empty?
+      @page_id = page_id || prediction['page_id']
+      @reconstructed = reconstructed
+    end
+
+    def to_s
+      @value ? @value.to_s : ''
+    end
+
+    # Multiply all the Mindee::Field confidences in the array.
+    def self.array_confidence(field_array)
+      product = 1
+      field_array.each do |field|
+        return 0.0 if field.confidence.nil?
+
+        product *= field.confidence
+      end
+      product.to_f
+    end
+
+    # Add all the Mindee::Field values in the array.
+    def self.array_sum(field_array)
+      arr_sum = 0
+      field_array.each do |field|
+        return 0.0 if field.value.nil?
+
+        arr_sum += field.value
+      end
+      arr_sum.to_f
+    end
+  end
+end

data/lib/mindee/fields/company_registration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Company registration number or code, and its type.
+  class CompanyRegistration < Field
+    # @return [String]
+    attr_reader :type
+
+    # @param prediction [Hash]
+    # @param page_id [Integer, nil]
+    # @param reconstructed [Boolean]
+    def initialize(prediction, page_id, reconstructed: false)
+      super
+      @type = prediction['type']
+    end
+  end
+end

data/lib/mindee/fields/datefield.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'date'
+
+require_relative 'base'
+
+module Mindee
+  # Represents a date.
+  class DateField < Field
+    # The date as a standard Ruby `Date` object.
+    # @return [Date, nil]
+    attr_reader :date_object
+    # The ISO 8601 representation of the date, regardless of the `raw` contents.
+    # @return [String, nil]
+    attr_reader :value
+    # The textual representation of the date as found on the document.
+    # @return [String, nil]
+    attr_reader :raw
+
+    # @param prediction [Hash]
+    # @param page_id [Integer, nil]
+    def initialize(prediction, page_id)
+      super
+      return unless @value
+
+      @date_object = Date.parse(@value)
+      @raw = prediction['raw']
+    end
+  end
+end