mindee 3.5.0 → 3.6.1

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

@@ -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/http/endpoint.rb

@@ -4,6 +4,7 @@ require 'json'
 require 'net/http'
 require_relative 'error'
 require_relative '../version'
+require_relative 'response_validation'
 
 module Mindee
   module HTTP
@@ -49,14 +50,15 @@ module Mindee
       # @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]
+      # @return [Array]
       def predict(input_source, all_words, close_file, cropper)
         check_api_key
         response = predict_req_post(input_source, all_words: all_words, close_file: close_file, cropper: cropper)
         hashed_response = JSON.parse(response.body, object_class: Hash)
-        return [hashed_response, response.body] if (200..299).include?(response.code.to_i)
+        return [hashed_response, response.body] if ResponseValidation.valid_sync_response?(response)
 
-        error = Error.handle_error!(@url_name, hashed_response, response.code.to_i)
+        ResponseValidation.clean_request!(response)
+        error = Error.handle_error(@url_name, response)
         raise error
       end
 
@@ -65,27 +67,29 @@ module Mindee
       # @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]
+      # @return [Array]
       def predict_async(input_source, all_words, close_file, cropper)
         check_api_key
         response = document_queue_req_get(input_source, all_words, close_file, cropper)
         hashed_response = JSON.parse(response.body, object_class: Hash)
-        return [hashed_response, response.body] if (200..299).include?(response.code.to_i)
+        return [hashed_response, response.body] if ResponseValidation.valid_async_response?(response)
 
-        error = Error.handle_error!(@url_name, hashed_response, response.code.to_i)
+        ResponseValidation.clean_request!(response)
+        error = Error.handle_error(@url_name, response)
         raise error
       end
 
       # Calls the parsed async doc.
       # @param job_id [String]
-      # @return [Hash]
+      # @return [Array]
       def parse_async(job_id)
         check_api_key
         response = document_queue_req(job_id)
         hashed_response = JSON.parse(response.body, object_class: Hash)
-        return [hashed_response, response.body] if (200..299).include?(response.code.to_i)
+        return [hashed_response, response.body] if ResponseValidation.valid_async_response?(response)
 
-        error = Error.handle_error!(@url_name, hashed_response, response.code.to_i)
+        ResponseValidation.clean_request!(response)
+        error = Error.handle_error(@url_name, response)
         raise error
       end
 
@@ -95,7 +99,7 @@ module Mindee
       # @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]
+      # @return [Net::HTTPResponse, nil]
       def predict_req_post(input_source, all_words: false, close_file: true, cropper: false)
         uri = URI("#{@url_root}/predict")
 
@@ -116,17 +120,18 @@ module Mindee
         form_data.push ['include_mvision', 'true'] if all_words
 
         req.set_form(form_data, 'multipart/form-data')
-
+        response = nil
         Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|
-          http.request(req)
+          response = http.request(req)
         end
+        response
       end
 
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
       # @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]
+      # @return [Net::HTTPResponse, nil]
       def document_queue_req_get(input_source, all_words, close_file, cropper)
         uri = URI("#{@url_root}/predict_async")
 
@@ -148,13 +153,15 @@ module Mindee
 
         req.set_form(form_data, 'multipart/form-data')
 
+        response = nil
         Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|
-          http.request(req)
+          response = http.request(req)
         end
+        response
       end
 
       # @param job_id [String]
-      # @return [Net::HTTPResponse]
+      # @return [Net::HTTPResponse, nil]
       def document_queue_req(job_id)
         uri = URI("#{@url_root}/documents/queue/#{job_id}")
 
@@ -171,8 +178,8 @@ module Mindee
 
         if response.code.to_i > 299 && response.code.to_i < 400
           req = Net::HTTP::Get.new(response['location'], headers)
-          response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|
-            http.request(req)
+          Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|
+            response = http.request(req)
           end
         end
         response

data/lib/mindee/http/error.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Mindee
   module HTTP
     # Mindee HTTP error module.
@@ -50,15 +52,20 @@ module Mindee
                       end
 
         end
-        error_obj
+        error_obj.nil? ? {} : error_obj
       end
 
       # Creates an appropriate HTTP error exception, based on retrieved http error code
       # @param url [String] the url of the product
       # @param response [Hash] dictionary response retrieved by the server
-      # @param code [Integer] http error code of the response
-      def handle_error!(url, response, code)
-        error_obj = create_error_obj(response)
+      def handle_error(url, response)
+        code = response.code.to_i
+        begin
+          parsed_hash = JSON.parse(response.body, object_class: Hash)
+        rescue JSON::ParserError
+          parsed_hash = response.body.to_s
+        end
+        error_obj = create_error_obj(parsed_hash)
         case code
         when 400..499
           MindeeHttpClientError.new(error_obj, url, code)

data/lib/mindee/http/response_validation.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+
+module Mindee
+  module HTTP
+    # Module dedicated to the validation & sanitizing of HTTP responses.
+    module ResponseValidation
+      # Checks if the synchronous response is valid. Returns True if the response is valid.
+      # @param [Net::HTTPResponse] response
+      # @return [Boolean]
+      def self.valid_sync_response?(response)
+        return false unless (200..399).cover?(response.code.to_i)
+
+        begin
+          JSON.parse(response.body, object_class: Hash)
+        rescue StandardError
+          return false
+        end
+        true
+      end
+
+      # Checks if the asynchronous response is valid. Also checks if it is a valid synchronous response.
+      # Returns true if the response is valid.
+      # @param [Net::HTTPResponse] response
+      # @return [Boolean]
+      def self.valid_async_response?(response)
+        return false unless valid_sync_response?(response)
+
+        return false unless (200..302).cover?(response.code.to_i)
+
+        hashed_response = JSON.parse(response.body, object_class: Hash)
+        return false if hashed_response.dig('job', 'error') && !hashed_response.dig('job', 'error').empty?
+
+        true
+      end
+
+      # Checks and correct the response object depending on the possible kinds of returns.
+      # @param response [Net::HTTPResponse]
+      def self.clean_request!(response)
+        return response if (response.code.to_i < 200) || (response.code.to_i > 302)
+
+        return response unless response.body.empty?
+
+        hashed_response = JSON.parse(response.body, object_class: Hash)
+        if hashed_response.dig('api_request', 'status_code').to_i > 399
+          response.instance_variable_set(:@code, hashed_response['api_request']['status_code'].to_s)
+        end
+        return unless hashed_response.dig('job', 'error').empty?
+
+        response.instance_variable_set(:@code, '500')
+      end
+    end
+  end
+end

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

@@ -14,6 +14,8 @@ module Mindee
         PROCESSING = :processing
         # Document parsing is complete.
         COMPLETED = :completed
+        # Job failed
+        FAILURE = :failed
       end
 
       # Potential values for requests.
@@ -36,10 +38,13 @@ module Mindee
         attr_reader :status
         # @return [Integer, nil]
         attr_reader :millisecs_taken
+        # @return [Hash, nil]
+        attr_reader :error
 
         # @param http_response [Hash]
         def initialize(http_response)
           @id = http_response['id']
+          @error = http_response['error']
           @issued_at = Time.iso8601(http_response['issued_at'])
           if http_response.key?('available_at') && !http_response['available_at'].nil?
             @available_at = Time.iso8601(http_response['available_at'])
@@ -108,7 +113,7 @@ module Mindee
           end
           if http_response.key?('document') &&
              (!http_response.key?('job') ||
-             http_response['job']['status'] == 'completed') &&
+               http_response['job']['status'] == 'completed') &&
              @api_request.status == RequestStatus::SUCCESS
             @document = Mindee::Parsing::Common::Document.new(product_class, http_response['document'])
           end

data/lib/mindee/parsing/standard/base_field.rb

@@ -96,7 +96,7 @@ module Mindee
           return '' if in_str.nil?
           return in_str if max_col_size.nil?
 
-          in_str.length < max_col_size ? in_str : "#{in_str[0..max_col_size - 4]}..."
+          in_str.length <= max_col_size ? in_str : "#{in_str[0..max_col_size - 4]}..."
         end
       end
     end

data/lib/mindee/product/.rubocop.yml

@@ -1,5 +1,10 @@
 inherit_from: ../../../.rubocop.yml
 
 Metrics/AbcSize:
-  Max: 75
-
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false

data/lib/mindee/product/eu/driver_license/driver_license_v1.rb

@@ -7,9 +7,9 @@ require_relative 'driver_license_v1_page'
 module Mindee
   module Product
     module EU
-      # EU Driver License module.
+      # Driver License module.
       module DriverLicense
-        # EU Driver License V1 prediction inference.
+        # Driver License V1 prediction inference.
         class DriverLicenseV1 < Mindee::Parsing::Common::Inference
           @endpoint_name = 'eu_driver_license'
           @endpoint_version = '1'

data/lib/mindee/product/eu/driver_license/driver_license_v1_document.rb

@@ -6,7 +6,7 @@ module Mindee
   module Product
     module EU
       module DriverLicense
-        # EU Driver License V1 document prediction.
+        # Driver License V1 document prediction.
         class DriverLicenseV1Document < Mindee::Parsing::Common::Prediction
           include Mindee::Parsing::Standard
           # EU driver license holders address

data/lib/mindee/product/eu/driver_license/driver_license_v1_page.rb

@@ -7,7 +7,7 @@ module Mindee
   module Product
     module EU
       module DriverLicense
-        # EU Driver License V1 page.
+        # Driver License V1 page.
         class DriverLicenseV1Page < Mindee::Parsing::Common::Page
           # @param prediction [Hash]
           def initialize(prediction)
@@ -19,7 +19,7 @@ module Mindee
           end
         end
 
-        # EU Driver License V1 page prediction.
+        # Driver License V1 page prediction.
         class DriverLicenseV1PagePrediction < DriverLicenseV1Document
           include Mindee::Parsing::Standard
 

data/lib/mindee/product/fr/carte_grise/carte_grise_v1_document.rb

@@ -133,7 +133,6 @@ module Mindee
           # @return [Mindee::Parsing::Standard::StringField]
           attr_reader :y6
 
-          # rubocop:disable Metrics/AbcSize
           # @param prediction [Hash]
           # @param page_id [Integer, nil]
           def initialize(prediction, page_id)
@@ -227,7 +226,6 @@ module Mindee
             out_str << "\n:MRZ Line 2: #{@mrz2}".rstrip
             out_str[1..].to_s
           end
-          # rubocop:enable Metrics/AbcSize
         end
       end
     end