mindee 3.4.0 → 3.6.0

data/docs/invoices_v4.md

@@ -310,6 +310,9 @@ puts result.document.inference.prediction.supplier_name.value
 ```rb
 for supplier_payment_details_elem in result.document.inference.prediction.supplier_payment_details do
   puts supplier_payment_details_elem.value
+    puts supplier_payment_details_elem.rate
+    puts supplier_payment_details_elem.code
+    puts supplier_payment_details_elem.basis
 end
 ```
 
@@ -318,7 +321,7 @@ end
 
 ```rb
 for taxes_elem in result.document.inference.prediction.taxes do
-  puts taxes_elem.to_s
+  puts taxes_elem.value
 end
 ```
 
@@ -344,4 +347,4 @@ puts result.document.inference.prediction.total_tax.value
 ```
 
 # Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/license_plates_v1.md

@@ -88,4 +88,4 @@ end
 ```
 
 # Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/multi_receipts_detector_v1.md

@@ -105,4 +105,4 @@ end
 ```
 
 # Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/passport_v1.md

@@ -183,4 +183,4 @@ puts result.document.inference.prediction.surname.value
 ```
 
 # Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/proof_of_address_v1.md

@@ -34,12 +34,12 @@ puts result.document
 ########
 Document
 ########
-:Mindee ID: 3a7e1da6-d4d0-4704-af91-051fe5484c2e
+:Mindee ID: 5d2361e9-405e-4fc1-8531-f92a3aef0c38
 :Filename: default_sample.jpg
 
 Inference
 #########
-:Product: mindee/proof_of_address v1.0
+:Product: mindee/proof_of_address v1.1
 :Rotation applied: Yes
 
 Prediction
@@ -47,7 +47,7 @@ Prediction
 :Locale: en; en; USD;
 :Issuer Name: PPL ELECTRIC UTILITIES
 :Issuer Company Registrations:
-:Issuer Address: 2 NORTH 9TH STREET CPC-GENN1 ALLENTOWN,PA 18101-1175
+:Issuer Address: 2 NORTH 9TH STREET CPC-GENN1 ALLENTOWN.PA 18101-1175
 :Recipient Name:
 :Recipient Company Registrations:
 :Recipient Address: 123 MAIN ST ANYTOWN,PA 18062
@@ -73,7 +73,7 @@ Page 0
 :Locale: en; en; USD;
 :Issuer Name: PPL ELECTRIC UTILITIES
 :Issuer Company Registrations:
-:Issuer Address: 2 NORTH 9TH STREET CPC-GENN1 ALLENTOWN,PA 18101-1175
+:Issuer Address: 2 NORTH 9TH STREET CPC-GENN1 ALLENTOWN.PA 18101-1175
 :Recipient Name:
 :Recipient Company Registrations:
 :Recipient Address: 123 MAIN ST ANYTOWN,PA 18062
@@ -204,4 +204,4 @@ puts result.document.inference.prediction.recipient_name.value
 ```
 
 # Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/resume_v1.md

@@ -0,0 +1,334 @@
+---
+title: Resume OCR Ruby
+---
+The Ruby OCR SDK supports the [Resume API](https://platform.mindee.com/mindee/resume).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/resume/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Resume sample](https://github.com/mindee/client-lib-test-data/blob/main/products/resume/default_sample.jpg?raw=true)
+
+# Quick-Start
+```rb
+require 'mindee'
+
+# Init a new client
+mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+
+# Load a file from disk
+input_source = mindee_client.source_from_path('/path/to/the/file.ext')
+
+# Parse the file
+result = mindee_client.enqueue_and_parse(
+  input_source,
+  Mindee::Product::Resume::ResumeV1
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document
+
+# Print the document-level parsed data
+# puts result.document.inference.prediction
+```
+
+**Output (RST):**
+```rst
+########
+Document
+########
+:Mindee ID: bc80bae0-af75-4464-95a9-2419403c75bf
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/resume v1.0
+:Rotation applied: No
+
+Prediction
+==========
+:Document Language: ENG
+:Document Type: RESUME
+:Given Names: Christopher
+:Surnames: Morgan
+:Nationality:
+:Email Address: christoper.m@gmail.com
+:Phone Number: +44 (0) 20 7666 8555
+:Address: 177 Great Portland Street, London W5W 6PQ
+:Social Networks:
+  +----------------------+----------------------------------------------------+
+  | Name                 | URL                                                |
+  +======================+====================================================+
+  | LinkedIn             | linkedin.com/christopher.morgan                    |
+  +----------------------+----------------------------------------------------+
+:Profession: Senior Web Developer
+:Job Applied:
+:Languages:
+  +----------+----------------------+
+  | Language | Level                |
+  +==========+======================+
+  | SPA      | Fluent               |
+  +----------+----------------------+
+  | ZHO      | Beginner             |
+  +----------+----------------------+
+  | DEU      | Intermediate         |
+  +----------+----------------------+
+:Hard Skills: HTML5
+              PHP OOP
+              JavaScript
+              CSS
+              MySQL
+:Soft Skills: Project management
+              Strong decision maker
+              Innovative
+              Complex problem solver
+              Creative design
+              Service-focused
+:Education:
+  +-----------------+---------------------------+-----------+----------+---------------------------+-------------+------------+
+  | Domain          | Degree                    | End Month | End Year | School                    | Start Month | Start Year |
+  +=================+===========================+===========+==========+===========================+=============+============+
+  | Computer Inf... | Bachelor                  |           |          | Columbia University, NY   |             | 2014       |
+  +-----------------+---------------------------+-----------+----------+---------------------------+-------------+------------+
+:Professional Experiences:
+  +-----------------+------------+---------------------------+-----------+----------+----------------------+-------------+------------+
+  | Contract Type   | Department | Employer                  | End Month | End Year | Role                 | Start Month | Start Year |
+  +=================+============+===========================+===========+==========+======================+=============+============+
+  | Full-Time       |            | Luna Web Design, New York | 05        | 2019     | Web Developer        | 09          | 2015       |
+  +-----------------+------------+---------------------------+-----------+----------+----------------------+-------------+------------+
+:Certificates:
+  +------------+--------------------------------+---------------------------+------+
+  | Grade      | Name                           | Provider                  | Year |
+  +============+================================+===========================+======+
+  |            | PHP Framework (certificate)... |                           | 2014 |
+  +------------+--------------------------------+---------------------------+------+
+  |            | Programming Languages: Java... |                           |      |
+  +------------+--------------------------------+---------------------------+------+
+```
+
+# Field Types
+## Standard Fields
+These fields are generic and used in several products.
+
+### Basic Field
+Each prediction object contains a set of fields that inherit from the generic `Field` class.
+A typical `Field` object will have the following attributes:
+
+* **value** (`String`, `Float`, `Integer`, `Boolean`): corresponds to the field value. Can be `nil` if no value was extracted.
+* **confidence** (Float, nil): the confidence score of the field prediction.
+* **bounding_box** (`Mindee::Geometry::Quadrilateral`, `nil`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document.
+* **polygon** (`Mindee::Geometry::Polygon`, `nil`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image.
+* **page_id** (`Integer`, `nil`): the ID of the page, is `nil` when at document-level.
+* **reconstructed** (`Boolean`): indicates whether an object was reconstructed (not extracted as the API gave it).
+
+
+Aside from the previous attributes, all basic fields have access to a `to_s` method that can be used to print their value as a string.
+
+
+### Classification Field
+The classification field `ClassificationField` does not implement all the basic `Field` attributes. It only implements **value**, **confidence** and **page_id**.
+
+> Note: a classification field's `value is always a `String`.
+
+### String Field
+The text field `StringField` only has one constraint: it's **value** is a `String` (or `nil`).
+
+## Specific Fields
+Fields which are specific to this product; they are not used in any other product.
+
+### Certificates Field
+The list of certificates obtained by the candidate.
+
+A `ResumeV1Certificate` implements the following attributes:
+
+* `grade` (String): The grade obtained for the certificate.
+* `name` (String): The name of certification.
+* `provider` (String): The organization or institution that issued the certificate.
+* `year` (String): The year when a certificate was issued or received.
+Fields which are specific to this product; they are not used in any other product.
+
+### Education Field
+The list of the candidate's educational background.
+
+A `ResumeV1Education` implements the following attributes:
+
+* `degree_domain` (String): The area of study or specialization.
+* `degree_type` (String): The type of degree obtained, such as Bachelor's, Master's, or Doctorate.
+* `end_month` (String): The month when the education program or course was completed.
+* `end_year` (String): The year when the education program or course was completed.
+* `school` (String): The name of the school.
+* `start_month` (String): The month when the education program or course began.
+* `start_year` (String): The year when the education program or course began.
+Fields which are specific to this product; they are not used in any other product.
+
+### Languages Field
+The list of languages that the candidate is proficient in.
+
+A `ResumeV1Language` implements the following attributes:
+
+* `language` (String): The language's ISO 639 code.
+* `level` (String): The candidate's level for the language.
+Fields which are specific to this product; they are not used in any other product.
+
+### Professional Experiences Field
+The list of the candidate's professional experiences.
+
+A `ResumeV1ProfessionalExperience` implements the following attributes:
+
+* `contract_type` (String): The type of contract for the professional experience.
+* `department` (String): The specific department or division within the company.
+* `employer` (String): The name of the company or organization.
+* `end_month` (String): The month when the professional experience ended.
+* `end_year` (String): The year when the professional experience ended.
+* `role` (String): The position or job title held by the candidate.
+* `start_month` (String): The month when the professional experience began.
+* `start_year` (String): The year when the professional experience began.
+Fields which are specific to this product; they are not used in any other product.
+
+### Social Networks Field
+The list of social network profiles of the candidate.
+
+A `ResumeV1SocialNetworksUrl` implements the following attributes:
+
+* `name` (String): The name of the social network.
+* `url` (String): The URL of the social network.
+
+# Attributes
+The following fields are extracted for Resume V1:
+
+## Address
+**address** ([StringField](#string-field)): The location information of the candidate, including city, state, and country.
+
+```rb
+puts result.document.inference.prediction.address.value
+```
+
+## Certificates
+**certificates** (Array<[ResumeV1Certificate](#certificates-field)>): The list of certificates obtained by the candidate.
+
+```rb
+for certificates_elem in result.document.inference.prediction.certificates do
+  puts certificates_elem.value
+end
+```
+
+## Document Language
+**document_language** ([StringField](#string-field)): The ISO 639 code of the language in which the document is written.
+
+```rb
+puts result.document.inference.prediction.document_language.value
+```
+
+## Document Type
+**document_type** ([ClassificationField](#classification-field)): The type of the document sent.
+
+```rb
+puts result.document.inference.prediction.document_type.value
+```
+
+## Education
+**education** (Array<[ResumeV1Education](#education-field)>): The list of the candidate's educational background.
+
+```rb
+for education_elem in result.document.inference.prediction.education do
+  puts education_elem.value
+end
+```
+
+## Email Address
+**email_address** ([StringField](#string-field)): The email address of the candidate.
+
+```rb
+puts result.document.inference.prediction.email_address.value
+```
+
+## Given Names
+**given_names** (Array<[StringField](#string-field)>): The candidate's first or given names.
+
+```rb
+for given_names_elem in result.document.inference.prediction.given_names do
+  puts given_names_elem.value
+end
+```
+
+## Hard Skills
+**hard_skills** (Array<[StringField](#string-field)>): The list of the candidate's technical abilities and knowledge.
+
+```rb
+for hard_skills_elem in result.document.inference.prediction.hard_skills do
+  puts hard_skills_elem.value
+end
+```
+
+## Job Applied
+**job_applied** ([StringField](#string-field)): The position that the candidate is applying for.
+
+```rb
+puts result.document.inference.prediction.job_applied.value
+```
+
+## Languages
+**languages** (Array<[ResumeV1Language](#languages-field)>): The list of languages that the candidate is proficient in.
+
+```rb
+for languages_elem in result.document.inference.prediction.languages do
+  puts languages_elem.value
+end
+```
+
+## Nationality
+**nationality** ([StringField](#string-field)): The ISO 3166 code for the country of citizenship of the candidate.
+
+```rb
+puts result.document.inference.prediction.nationality.value
+```
+
+## Phone Number
+**phone_number** ([StringField](#string-field)): The phone number of the candidate.
+
+```rb
+puts result.document.inference.prediction.phone_number.value
+```
+
+## Profession
+**profession** ([StringField](#string-field)): The candidate's current profession.
+
+```rb
+puts result.document.inference.prediction.profession.value
+```
+
+## Professional Experiences
+**professional_experiences** (Array<[ResumeV1ProfessionalExperience](#professional-experiences-field)>): The list of the candidate's professional experiences.
+
+```rb
+for professional_experiences_elem in result.document.inference.prediction.professional_experiences do
+  puts professional_experiences_elem.value
+end
+```
+
+## Social Networks
+**social_networks_urls** (Array<[ResumeV1SocialNetworksUrl](#social-networks-field)>): The list of social network profiles of the candidate.
+
+```rb
+for social_networks_urls_elem in result.document.inference.prediction.social_networks_urls do
+  puts social_networks_urls_elem.value
+end
+```
+
+## Soft Skills
+**soft_skills** (Array<[StringField](#string-field)>): The list of the candidate's interpersonal and communication abilities.
+
+```rb
+for soft_skills_elem in result.document.inference.prediction.soft_skills do
+  puts soft_skills_elem.value
+end
+```
+
+## Surnames
+**surnames** (Array<[StringField](#string-field)>): The candidate's last names.
+
+```rb
+for surnames_elem in result.document.inference.prediction.surnames do
+  puts surnames_elem.value
+end
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/us_driver_license_v1.md

@@ -54,7 +54,7 @@ Prediction
 :Date Of Birth: 1957-02-01
 :Restrictions: NONE
 :Endorsements: NONE
-:Class:
+:Driver License Class: D
 :Sex: M
 :Height: 5-08
 :Weight: 185
@@ -79,7 +79,7 @@ Page 0
 :Date Of Birth: 1957-02-01
 :Restrictions: NONE
 :Endorsements: NONE
-:Class:
+:Driver License Class: D
 :Sex: M
 :Height: 5-08
 :Weight: 185
@@ -265,4 +265,4 @@ puts result.document.inference.prediction.weight.value
 ```
 
 # Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/us_w9_v1.md

@@ -204,4 +204,4 @@ end
 ```
 
 # Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/lib/mindee/client.rb

@@ -38,6 +38,7 @@ 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::Parsing::Common::ApiResponse]
     def parse(
       input_source,
@@ -80,6 +81,7 @@ 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::Parsing::Common::ApiResponse]
     def enqueue(
       input_source,
@@ -118,7 +120,6 @@ module Mindee
     end
 
     # rubocop:disable Metrics/ParameterLists
-
     # Enqueue a document for async parsing and automatically try to retrieve it
     #
     # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
@@ -139,7 +140,7 @@ module Mindee
     #  This performs a cropping operation on the server and will increase response time.
     # @param initial_delay_sec [Integer, Float, nil] initial delay before polling. Defaults to 4.
     # @param delay_sec [Integer, Float, nil] delay between polling attempts. Defaults to 2.
-    # @param max_retries [Integer, nil] maximum amount of retries. Defaults to 30.
+    # @param max_retries [Integer, nil] maximum amount of retries. Defaults to 60.
     # @return [Mindee::Parsing::Common::ApiResponse]
     def enqueue_and_parse(
       input_source,
@@ -151,7 +152,7 @@ module Mindee
       cropper: false,
       initial_delay_sec: 4,
       delay_sec: 2,
-      max_retries: 30
+      max_retries: 60
     )
       enqueue_res = enqueue(
         input_source,
@@ -178,6 +179,7 @@ module Mindee
 
       queue_res
     end
+
     # rubocop:enable Metrics/ParameterLists
 
     # Load a document from an absolute path, as a string.

data/lib/mindee/http/endpoint.rb

@@ -46,9 +46,9 @@ module Mindee
 
       # Call the prediction API.
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
-      # @param all_words [Boolean]
-      # @param close_file [Boolean]
-      # @param cropper [Boolean]
+      # @param all_words [Boolean] Whether the full word extraction needs to be performed
+      # @param close_file [Boolean] Whether the file will be closed after reading
+      # @param cropper [Boolean] Whether a cropping operation will be applied
       # @return [Hash]
       def predict(input_source, all_words, close_file, cropper)
         check_api_key
@@ -62,8 +62,9 @@ module Mindee
 
       # Call the prediction API.
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
-      # @param close_file [Boolean]
-      # @param cropper [Boolean]
+      # @param all_words [Boolean] Whether the full word extraction needs to be performed
+      # @param close_file [Boolean] Whether the file will be closed after reading
+      # @param cropper [Boolean] Whether a cropping operation will be applied
       # @return [Hash]
       def predict_async(input_source, all_words, close_file, cropper)
         check_api_key
@@ -91,10 +92,10 @@ module Mindee
       private
 
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
-      # @param all_words [Boolean]
-      # @param close_file [Boolean]
-      # @param cropper [Boolean]
-      # @return [Net::HTTPResponse]
+      # @param all_words [Boolean] Whether the full word extraction needs to be performed
+      # @param close_file [Boolean] Whether the file will be closed after reading
+      # @param cropper [Boolean] Whether a cropping operation will be applied
+      # @return [Net::HTTP, nil]
       def predict_req_post(input_source, all_words: false, close_file: true, cropper: false)
         uri = URI("#{@url_root}/predict")
 
@@ -122,9 +123,9 @@ module Mindee
       end
 
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
-      # @param all_words [Boolean]
-      # @param close_file [Boolean]
-      # @param cropper [Boolean]
+      # @param all_words [Boolean] Whether the full word extraction needs to be performed
+      # @param close_file [Boolean] Whether the file will be closed after reading
+      # @param cropper [Boolean] Whether a cropping operation will be applied
       # @return [Net::HTTPResponse]
       def document_queue_req_get(input_source, all_words, close_file, cropper)
         uri = URI("#{@url_root}/predict_async")

data/lib/mindee/input/sources.rb

@@ -7,6 +7,7 @@ require_relative '../pdf'
 
 module Mindee
   module Input
+    # Document source handling.
     module Source
       # Mime types accepted by the server.
       ALLOWED_MIME_TYPES = [
@@ -107,8 +108,7 @@ module Mindee
           @io_stream = PdfProcessor.parse(@io_stream, options)
         end
 
-        # Reads a document. Packs it into bytes if needed.
-        # Note: only needs filename in case of some pdf files.
+        # Reads a document.
         # @param close [Boolean]
         # @return [Array<String, [String, aBinaryString ], [Hash, nil] >]
         def read_document(close: true)
@@ -116,9 +116,7 @@ module Mindee
           # Avoids needlessly re-packing some files
           data = @io_stream.read
           @io_stream.close if close
-          return ['document', data, { filename: @filename }] if pdf?
-
-          ['document', [data].pack('m')]
+          ['document', data, { filename: Mindee::Input::Source.convert_to_unicode_escape(@filename) }]
         end
       end
 
@@ -142,6 +140,16 @@ module Mindee
           io_stream.set_encoding Encoding::BINARY
           super(io_stream, filename, fix_pdf: fix_pdf)
         end
+
+        # Overload of the same function to prevent a base64 from being re-encoded.
+        # @param close [Boolean]
+        # @return [Array<String, [String, aBinaryString ], [Hash, nil] >]
+        def read_document(close: true)
+          @io_stream.seek(0)
+          data = @io_stream.read
+          @io_stream.close if close
+          ['document', [data].pack('m'), { filename: Source.convert_to_unicode_escape(@filename) }]
+        end
       end
 
       # Load a document from raw bytes.
@@ -178,6 +186,21 @@ module Mindee
           @url = url
         end
       end
+
+      # Replaces non-ASCII characters by their unicode escape sequence.
+      # Keeps other characters as is.
+      # @return A clean String.
+      def self.convert_to_unicode_escape(string)
+        unicode_escape_string = ''.dup
+        string.each_char do |char|
+          unicode_escape_string << if char.bytesize > 1
+                                     "\\u#{char.unpack1('U').to_s(16).rjust(4, '0')}"
+                                   else
+                                     char
+                                   end
+        end
+        unicode_escape_string
+      end
     end
   end
 end

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

@@ -34,8 +34,10 @@ module Mindee
           out_str << "\n:Rotation applied: #{is_rotation_applied}"
           out_str << "\n\nPrediction\n=========="
           out_str << "\n#{@prediction.to_s.size.positive? ? "#{@prediction}\n" : ''}"
-          out_str << "\nPage Predictions\n================\n\n"
+          out_str << "\nPage Predictions\n================\n\n" unless @pages.empty?
           out_str << @pages.map(&:to_s).join("\n\n")
+          out_str.rstrip!
+          out_str
         end
       end
     end