mindee 1.0.0

data/lib/mindee/client.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative 'inputs'
+require_relative 'document_config'
+require_relative 'endpoint'
+
+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
+    end
+
+    # Call prediction API on the document and parse the results.
+    # @param document_name [String] Document name (type) to parse
+    # @param username [String] API username, the endpoint owner
+    # @param include_words [Boolean] Include all the words of the document in the response
+    # @param close_file [Boolean] Whether to close the file after parsing it.
+    # @return [Mindee::DocumentResponse]
+    def parse(document_name, username: '', include_words: false, close_file: true)
+      found = []
+      @doc_configs.each_key do |conf|
+        found.push(conf) if conf[1] == document_name
+      end
+      raise "Document type not configured: #{document_name}" if found.empty?
+
+      if !username.empty?
+        config_key = [username, document_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 '#{document_name}' in your custom config.\n" \
+              "To avoid confusion, please add the 'account_name' attribute to " \
+              "the parse method, one of #{usernames}."
+      end
+
+      doc_config = @doc_configs[config_key]
+      doc_config.predict(@input_doc, include_words, close_file)
+    end
+  end
+
+  # Mindee API Client.
+  # See: https://developers.mindee.com/docs/
+  class Client
+    DOC_TYPE_INVOICE = 'invoice'
+    DOC_TYPE_RECEIPT = 'receipt'
+    DOC_TYPE_PASSPORT = 'passport'
+    DOC_TYPE_FINANCIAL = 'financial_doc'
+
+    # @param raise_on_error [Boolean]
+    def initialize(api_key: nil, raise_on_error: true)
+      @raise_on_error = raise_on_error
+      @doc_configs = {}
+      @api_key = api_key
+    end
+
+    # Configure a 'Mindee Invoice' document.
+    # @param api_key [String] Override the client API key for this endpoint
+    # @return [Mindee::Client]
+    def config_invoice(api_key: nil)
+      @doc_configs[['mindee', DOC_TYPE_INVOICE]] = InvoiceConfig.new(
+        api_key || @api_key,
+        @raise_on_error
+      )
+      self
+    end
+
+    # Configure a 'Mindee Expense Receipts' document.
+    # @param api_key [String] Override the client API key for this endpoint
+    # @return [Mindee::Client]
+    def config_receipt(api_key: nil)
+      @doc_configs[['mindee', DOC_TYPE_RECEIPT]] = ReceiptConfig.new(
+        api_key || @api_key,
+        @raise_on_error
+      )
+      self
+    end
+
+    # Configure a 'Mindee Passport' document.
+    # @param api_key [String] Override the client API key for this endpoint
+    # @return [Mindee::Client]
+    def config_passport(api_key: nil)
+      @doc_configs[['mindee', DOC_TYPE_PASSPORT]] = PassportConfig.new(
+        api_key || @api_key,
+        @raise_on_error
+      )
+      self
+    end
+
+    # Configure a 'Mindee Financial document'. Uses 'Invoice' and 'Expense Receipt' internally.
+    # @param api_key [String] Override the client API key for this endpoint
+    # @return [Mindee::Client]
+    def config_financial_doc(api_key: nil)
+      @doc_configs[['mindee', DOC_TYPE_FINANCIAL]] = FinancialDocConfig.new(
+        api_key || @api_key,
+        @raise_on_error
+      )
+      self
+    end
+
+    # Configure a custom document using the 'Mindee API Builder'.
+    # @param account_name [String] Your organization's username on the API Builder
+    # @param document_name [String] The "API name" field in the "Settings" page of the API Builder
+    # @param api_key [String]  Override the client API key for this endpoint
+    # @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 config_custom_doc(
+      document_name,
+      account_name,
+      api_key: nil,
+      version: '1'
+    )
+      @doc_configs[[account_name, document_name]] = CustomDocConfig.new(
+        document_name,
+        account_name,
+        version,
+        api_key || @api_key,
+        @raise_on_error
+      )
+      self
+    end
+
+    # Load a document from an absolute path, as a string.
+    # @param input_path [String] Path of file to open
+    # @param cut_pages [Boolean] Automatically reconstruct a multi-page document.
+    # @param max_pages [Integer] Number (between 1 and 3 incl.) of pages to reconstruct a document.
+    # @return [Mindee::DocumentClient]
+    def doc_from_path(input_path, cut_pages: true, max_pages: MAX_DOC_PAGES)
+      doc = PathDocument.new(input_path, cut_pages, max_pages: max_pages)
+      DocumentClient.new(doc, @doc_configs)
+    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)
+    # @param cut_pages [Boolean] Automatically reconstruct a multi-page document.
+    # @param max_pages [Integer] Number (between 1 and 3 incl.) of pages to reconstruct a document.
+    # @return [Mindee::DocumentClient]
+    def doc_from_bytes(input_bytes, filename, cut_pages: true, max_pages: MAX_DOC_PAGES)
+      doc = BytesDocument.new(input_bytes, filename, cut_pages, max_pages: max_pages)
+      DocumentClient.new(doc, @doc_configs)
+    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)
+    # @param cut_pages [Boolean] Automatically reconstruct a multi-page document.
+    # @param max_pages [Integer] Number (between 1 and 3 incl.) of pages to reconstruct a document.
+    # @return [Mindee::DocumentClient]
+    def doc_from_b64string(base64_string, filename, cut_pages: true, max_pages: MAX_DOC_PAGES)
+      doc = Base64Document.new(base64_string, filename, cut_pages, max_pages: max_pages)
+      DocumentClient.new(doc, @doc_configs)
+    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)
+    # @param cut_pages [Boolean] Automatically reconstruct a multi-page document.
+    # @param max_pages [Integer] Number (between 1 and 3 incl.) of pages to reconstruct a document.
+    # @return [Mindee::DocumentClient]
+    def doc_from_file(input_file, filename, cut_pages: true, max_pages: MAX_DOC_PAGES)
+      doc = FileDocument.new(input_file, filename, cut_pages, max_pages: max_pages)
+      DocumentClient.new(doc, @doc_configs)
+    end
+  end
+end

data/lib/mindee/document_config.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'endpoint'
+require_relative 'documents'
+require_relative 'response'
+
+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
+
+    # @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)
+    end
+
+    # Call the prediction API.
+    # @param input_doc [Mindee::InputDocument]
+    # @param include_words [Boolean]
+    # @param close_file [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)
+    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]
+    # @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
+      )
+    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
+
+  # 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)
+    end
+  end
+end

data/lib/mindee/documents/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Base document object.
+  class Document
+    # document type
+    # @return [String]
+    attr_reader :document_type
+    # Validation checks for the document
+    # @return [Hash<Symbol, Boolean>]
+    attr_reader :checklist
+    # Original filename of the document
+    # @return [String, nil]
+    attr_reader :filename
+    # Detected MIME type of the document
+    # @return [String, nil]
+    attr_reader :file_mimetype
+
+    # @param input_file [Mindee::InputDocument, nil]
+    # @param document_type [String]
+    def initialize(document_type, input_file: nil)
+      @document_type = document_type
+      unless input_file.nil?
+        @filename = input_file.filename
+        @file_mimetype = input_file.file_mimetype
+      end
+      @checklist = {}
+    end
+
+    # @return [Boolean]
+    def all_checks
+      @checklist.all? { |_, value| value == true }
+    end
+  end
+end

data/lib/mindee/documents/custom.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative '../fields'
+require_relative 'base'
+
+module Mindee
+  # Custom document object.
+  class CustomDocument < Document
+    # All fields in the document
+    # @return [Hash<Symbol, Mindee::ListField>]
+    attr_reader :fields
+
+    # @param document_type [String]
+    # @param prediction [Hash]
+    # @param input_file [Mindee::InputDocument, nil]
+    # @param page_id [Integer, nil]
+    def initialize(document_type, prediction, input_file: nil, page_id: nil)
+      super(document_type, input_file: input_file)
+      @fields = {}
+      prediction.each do |field_name, field_prediction|
+        field_sym = field_name.to_sym
+        complete_field = ListField.new(field_prediction, page_id)
+
+        # Add the field to the `fields` array
+        @fields[field_sym] = complete_field
+
+        # Create a dynamic accessor function for the field
+        singleton_class.module_eval { attr_accessor field_sym }
+        send("#{field_sym}=", complete_field)
+      end
+    end
+
+    def to_s
+      out_str = String.new
+      out_str << "----- #{@document_type} -----"
+      out_str << "\nFilename: #{@filename}".rstrip
+      @fields.each do |name, info|
+        out_str << "\n#{name}: #{info}".rstrip
+      end
+      out_str << "\n----------------------"
+      out_str
+    end
+  end
+end

data/lib/mindee/documents/financial_doc.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative '../fields'
+require_relative 'base'
+require_relative 'invoice'
+require_relative 'receipt'
+
+module Mindee
+  # Union of `Invoice` and `Receipt`.
+  class FinancialDocument < 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 :category
+    # @return [Mindee::Field]
+    attr_reader :invoice_number
+    # @return [Mindee::Field]
+    attr_reader :time
+    # @return [Mindee::DateField]
+    attr_reader :due_date
+    # @return [Array<Mindee::TaxField>]
+    attr_reader :taxes
+    # @return [Mindee::Field]
+    attr_reader :supplier
+    # @return [Mindee::Field]
+    attr_reader :supplier_address
+    # @return [Mindee::Field]
+    attr_reader :customer_name
+    # @return [Mindee::Field]
+    attr_reader :customer_address
+    # @return [Array<Mindee::CompanyRegistration>]
+    attr_reader :company_registration
+    # @return [Array<Mindee::CompanyRegistration>]
+    attr_reader :customer_company_registration
+    # @return [Array<Mindee::PaymentDetails>]
+    attr_reader :payment_details
+
+    # @param prediction [Hash]
+    # @param input_file [Mindee::InputDocument, nil]
+    # @param page_id [Integer, nil]
+    def initialize(prediction, input_file: nil, page_id: nil)
+      super('financial_doc', input_file: input_file)
+      @locale = Locale.new(prediction['locale'])
+      if prediction.include? 'invoice_number'
+        build_from_invoice(
+          Invoice.new(prediction, input_file: input_file, page_id: page_id)
+        )
+      else
+        build_from_receipt(
+          Receipt.new(prediction, input_file: input_file, page_id: page_id)
+        )
+      end
+    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 << '-----Financial Document data-----'
+      out_str << "\nFilename: #{@filename}".rstrip
+      out_str << "\nCategory: #{@category}".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 << "\nTime: #{@time}".rstrip
+      out_str << "\nLocale: #{@locale}".rstrip
+      out_str << "\n----------------------"
+      out_str
+    end
+
+    private
+
+    # @param invoice [Mindee::Invoice]
+    def build_from_invoice(invoice)
+      @orientation = invoice.orientation
+      @category = empty_field
+      @total_incl = invoice.total_incl
+      @total_excl = invoice.total_excl
+      @total_tax = invoice.total_tax
+      @date = invoice.date
+      @time = empty_field
+      @due_date = invoice.due_date
+      @invoice_number = invoice.invoice_number
+      @taxes = invoice.taxes
+      @supplier = invoice.supplier
+      @supplier_address = invoice.supplier_address
+      @company_registration = invoice.company_registration
+      @customer_company_registration = invoice.customer_company_registration
+      @payment_details = invoice.payment_details
+    end
+
+    # @param receipt [Mindee::Receipt]
+    def build_from_receipt(receipt)
+      @orientation = receipt.orientation
+      @category = receipt.category
+      @total_incl = receipt.total_incl
+      @total_excl = receipt.total_excl
+      @total_tax = receipt.total_tax
+      @date = receipt.date
+      @time = receipt.time
+      @due_date = empty_field
+      @taxes = receipt.taxes
+      @supplier = receipt.supplier
+      @supplier_address = empty_field
+      @company_registration = empty_field
+      @customer_company_registration = empty_field
+      @payment_details = empty_field
+    end
+
+    def empty_field
+      Mindee::Field.new({}, nil)
+    end
+  end
+end