mindee 3.10.0 → 3.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdc0f8cc57ce32684b3da523ce0a6666a251ff90d7a6d894a7b4601231bed3e4
-  data.tar.gz: e249e12de6c86cc4a7683392504d5cd914afb941a99b5b00bff3f90fd0f4ae36
+  metadata.gz: ef77c472e79a3139844c6e719cb368c081466ceed4ded849a39eefb27484ca78
+  data.tar.gz: 4d41a61f23ccad56d6f9e4a846feed4c67c613d17a80baf0191aec119eb0835a
 SHA512:
-  metadata.gz: 713cf8cb6259b54637865f6799db1f5da7d7f27c436960316f84e2d404fe743d343d2d307feb2023c0fcab580421e5e0004bc70d34735d5800f0530d135c70ea
-  data.tar.gz: 535dc099fe76a27b3af26bb5cb726756e1b158056027782b607820e2648b92dbc32e65cf453d356c33355c5b94a3df9ffbbd86fabfc18fd5f439b48efa68816c
+  metadata.gz: df1777eaec4a97d7524e0bf0cc3e2356169a9a62af6349a10abacc8d1977c83124cbdeafed2e1d94f4cef4e3986c5e488fea45c31c1048c3feed85cdc8e0fb74
+  data.tar.gz: 998987a5877b57d1ef2fc078c144f247369c2824b5a84334297e2bed81e61a77b894a863d5a4920d23cb3093b18f86bb0201b7e51a971136f3c2c1bb33c065ea

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Mindee Ruby API Library Changelog
 
+## v3.12.0 - 2024-07-24
+### Changes
+* :sparkles: add support for Multi-Receipts Extraction
+* :sparkles: add support for Healthcare Card V1
+* :sparkles: add support for Invoice V4.7
+* :sparkles: add support for Financial Document V1.9
+* :recycle: update display for company registration fields
+
+
+## v3.11.0 - 2024-06-10
+### Changes
+* :sparkles: add custom tax extraction feature (#76)
+
+
 ## v3.10.0 - 2024-05-31
 ### Changes
 * :sparkles: add support for us mail v2 (#98)

data/bin/mindee.rb

@@ -35,7 +35,7 @@ DOCUMENTS = {
     description: 'Financial Document',
     doc_class: Mindee::Product::FinancialDocument::FinancialDocumentV1,
     sync: true,
-    async: false,
+    async: true,
   },
   "invoice" => {
     description: 'Invoice',
@@ -115,6 +115,12 @@ DOCUMENTS = {
     sync: true,
     async: false,
   },
+  "us-heathcare-card" => {
+    description: "US Healthcare Card",
+    doc_class: Mindee::Product::US::HealthcareCard::HealthcareCardV1,
+    sync: false,
+    async: true
+  },
   "us-w9" => {
     description: "US W9 Form",
     doc_class: Mindee::Product::US::W9::W9V1,

data/docs/code_samples/financial_document_v1_async.txt

@@ -0,0 +1,19 @@
+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::FinancialDocument::FinancialDocumentV1
+)
+
+# 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

data/docs/code_samples/us_healthcare_cards_v1_async.txt

@@ -0,0 +1,19 @@
+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::US::HealthcareCard::HealthcareCardV1
+)
+
+# 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

data/docs/expense_receipts_v5.md

@@ -34,12 +34,12 @@ puts result.document
 ########
 Document
 ########
-:Mindee ID: ce41e37a-65d8-4de1-b34b-1c92ab04b1ae
+:Mindee ID: d96fb043-8fb8-4adc-820c-387aae83376d
 :Filename: default_sample.jpg
 
 Inference
 #########
-:Product: mindee/expense_receipts v5.0
+:Product: mindee/expense_receipts v5.3
 :Rotation applied: Yes
 
 Prediction
@@ -60,11 +60,12 @@ Prediction
   +===============+========+==========+===============+
   | 8.50          | VAT    | 20.00    | 1.70          |
   +---------------+--------+----------+---------------+
-:Supplier Name: CLACHAN
-:Supplier Company Registrations: 232153895
-                                 232153895
-:Supplier Address: 34 kingley street w1b 5qh
+:Supplier Name: clachan
+:Supplier Company Registrations: Type: VAT NUMBER, Value: 232153895
+                                 Type: VAT NUMBER, Value: 232153895
+:Supplier Address: 34 Kingley Street W1B 50H
 :Supplier Phone Number: 02074940834
+:Receipt Number: 54/7500
 :Line Items:
   +--------------------------------------+----------+--------------+------------+
   | Description                          | Quantity | Total Amount | Unit Price |
@@ -93,11 +94,12 @@ Page 0
   +===============+========+==========+===============+
   | 8.50          | VAT    | 20.00    | 1.70          |
   +---------------+--------+----------+---------------+
-:Supplier Name: CLACHAN
-:Supplier Company Registrations: 232153895
-                                 232153895
-:Supplier Address: 34 kingley street w1b 5qh
+:Supplier Name: clachan
+:Supplier Company Registrations: Type: VAT NUMBER, Value: 232153895
+                                 Type: VAT NUMBER, Value: 232153895
+:Supplier Address: 34 Kingley Street W1B 50H
 :Supplier Phone Number: 02074940834
+:Receipt Number: 54/7500
 :Line Items:
   +--------------------------------------+----------+--------------+------------+
   | Description                          | Quantity | Total Amount | Unit Price |

data/docs/financial_document_v1.md

@@ -29,23 +29,49 @@ puts result.document
 # puts result.document.inference.prediction
 ```
 
+You can also call this product asynchronously:
+
+```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::FinancialDocument::FinancialDocumentV1
+)
+
+# 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: 503895c6-eced-42e2-a6fc-0292b7ccf680
+:Mindee ID: 3859a462-e05f-4f4c-a736-febca66b9aa9
 :Filename: default_sample.jpg
 
 Inference
 #########
-:Product: mindee/financial_document v1.6
+:Product: mindee/financial_document v1.9
 :Rotation applied: Yes
 
 Prediction
 ==========
-:Locale: en; USD;
+:Locale: en; en; USD;
 :Invoice Number: INT-001
+:Receipt Number:
+:Document Number: INT-001
 :Reference Numbers: 2412/2019
 :Purchase Date: 2019-11-02
 :Due Date: 2019-02-26
@@ -77,23 +103,25 @@ Prediction
 :Tip and Gratuity:
 :Purchase Time:
 :Line Items:
-  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
-  | Description                          | Product code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit Price |
-  +======================================+==============+==========+============+==============+==============+============+
-  | Front and rear brake cables          |              | 1.00     |            |              | 100.00       | 100.00     |
-  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
-  | New set of pedal arms                |              | 2.00     |            |              | 50.00        | 25.00      |
-  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
-  | Labor 3hrs                           |              | 3.00     |            |              | 45.00        | 15.00      |
-  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+-----------------+------------+
+  | Description                          | Product code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit of measure | Unit Price |
+  +======================================+==============+==========+============+==============+==============+=================+============+
+  | Front and rear brake cables          |              | 1.00     |            |              | 100.00       |                 | 100.00     |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+-----------------+------------+
+  | New set of pedal arms                |              | 2.00     |            |              | 50.00        |                 | 25.00      |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+-----------------+------------+
+  | Labor 3hrs                           |              | 3.00     |            |              | 45.00        |                 | 15.00      |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+-----------------+------------+
 
 Page Predictions
 ================
 
 Page 0
 ------
-:Locale: en; USD;
+:Locale: en; en; USD;
 :Invoice Number: INT-001
+:Receipt Number:
+:Document Number: INT-001
 :Reference Numbers: 2412/2019
 :Purchase Date: 2019-11-02
 :Due Date: 2019-02-26
@@ -125,15 +153,15 @@ Page 0
 :Tip and Gratuity:
 :Purchase Time:
 :Line Items:
-  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
-  | Description                          | Product code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit Price |
-  +======================================+==============+==========+============+==============+==============+============+
-  | Front and rear brake cables          |              | 1.00     |            |              | 100.00       | 100.00     |
-  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
-  | New set of pedal arms                |              | 2.00     |            |              | 50.00        | 25.00      |
-  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
-  | Labor 3hrs                           |              | 3.00     |            |              | 45.00        | 15.00      |
-  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+-----------------+------------+
+  | Description                          | Product code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit of measure | Unit Price |
+  +======================================+==============+==========+============+==============+==============+=================+============+
+  | Front and rear brake cables          |              | 1.00     |            |              | 100.00       |                 | 100.00     |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+-----------------+------------+
+  | New set of pedal arms                |              | 2.00     |            |              | 50.00        |                 | 25.00      |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+-----------------+------------+
+  | Labor 3hrs                           |              | 3.00     |            |              | 45.00        |                 | 15.00      |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+-----------------+------------+
 ```
 
 # Field Types
@@ -220,6 +248,7 @@ A `FinancialDocumentV1LineItem` implements the following attributes:
 * `tax_amount` (Float): The item tax amount.
 * `tax_rate` (Float): The item tax rate in percentage.
 * `total_amount` (Float): The item total amount.
+* `unit_measure` (String): The item unit of measure.
 * `unit_price` (Float): The item unit price.
 
 # Attributes

data/docs/invoices_v4.md

@@ -34,7 +34,7 @@ puts result.document
 ########
 Document
 ########
-:Mindee ID: 5c0371d0-1433-43a4-b8fb-a3b11aaf9a0e
+:Mindee ID: 128a314f-1adb-42eb-a9e3-402055a8b8ce
 :Filename: default_sample.jpg
 
 Inference
@@ -49,7 +49,7 @@ Prediction
 :Reference Numbers: AD29094
 :Purchase Date: 2018-09-25
 :Due Date:
-:Total Net:
+:Total Net: 2145.00
 :Total Amount: 2608.20
 :Total Tax: 193.20
 :Taxes:
@@ -93,7 +93,7 @@ Page 0
 :Reference Numbers: AD29094
 :Purchase Date: 2018-09-25
 :Due Date:
-:Total Net:
+:Total Net: 2145.00
 :Total Amount: 2608.20
 :Total Tax: 193.20
 :Taxes:
@@ -212,6 +212,7 @@ A `InvoiceV4LineItem` implements the following attributes:
 * `tax_amount` (Float): The item tax amount.
 * `tax_rate` (Float): The item tax rate in percentage.
 * `total_amount` (Float): The item total amount.
+* `unit_measure` (String): The item unit of measure.
 * `unit_price` (Float): The item unit price.
 
 # Attributes

data/docs/us_healthcare_cards_v1.md

@@ -0,0 +1,204 @@
+---
+title: US Healthcare Card OCR Ruby
+---
+The Ruby OCR SDK supports the [Healthcare Card API](https://platform.mindee.com/mindee/us_healthcare_cards).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/us_healthcare_cards/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Healthcare Card sample](https://github.com/mindee/client-lib-test-data/blob/main/products/us_healthcare_cards/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::US::HealthcareCard::HealthcareCardV1
+)
+
+# 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: 0ced9f49-00c0-4a1d-8221-4a1538813a95
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/us_healthcare_cards v1.0
+:Rotation applied: No
+
+Prediction
+==========
+:Company Name: UnitedHealthcare
+:Member Name: SUBSCRIBER SMITH
+:Member ID: 123456789
+:Issuer 80840:
+:Dependents: SPOUSE SMITH
+             CHILD1 SMITH
+             CHILD2 SMITH
+             CHILD3 SMITH
+:Group Number: 98765
+:Payer ID: 87726
+:RX BIN: 610279
+:RX GRP: UHEALTH
+:RX PCN: 9999
+:copays:
+  +--------------+--------------+
+  | Service Fees | Service Name |
+  +==============+==============+
+  | 20.00        | office visit |
+  +--------------+--------------+
+  | 300.00       | emergency    |
+  +--------------+--------------+
+  | 75.00        | urgent care  |
+  +--------------+--------------+
+  | 30.00        | specialist   |
+  +--------------+--------------+
+:Enrollment Date: 2023-09-13
+```
+
+# 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.
+
+### Date Field
+Aside from the basic `Field` attributes, the date field `DateField` also implements the following: 
+
+* **date_object** (`Date`): an accessible representation of the value as a JavaScript object.
+
+### 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.
+
+### copays Field
+Is a fixed amount for a covered service.
+
+A `HealthcareCardV1Copay` implements the following attributes:
+
+* `service_fees` (Float): The price of service.
+* `service_name` (String): The name of service of the copay.
+
+# Attributes
+The following fields are extracted for Healthcare Card V1:
+
+## Company Name
+**company_name** ([StringField](#string-field)): The name of the company that provides the healthcare plan.
+
+```rb
+puts result.document.inference.prediction.company_name.value
+```
+
+## copays
+**copays** (Array<[HealthcareCardV1Copay](#copays-field)>): Is a fixed amount for a covered service.
+
+```rb
+for copays_elem in result.document.inference.prediction.copays do
+  puts copays_elem.value
+end
+```
+
+## Dependents
+**dependents** (Array<[StringField](#string-field)>): The list of dependents covered by the healthcare plan.
+
+```rb
+for dependents_elem in result.document.inference.prediction.dependents do
+  puts dependents_elem.value
+end
+```
+
+## Enrollment Date
+**enrollment_date** ([DateField](#date-field)): The date when the member enrolled in the healthcare plan.
+
+```rb
+puts result.document.inference.prediction.enrollment_date.value
+```
+
+## Group Number
+**group_number** ([StringField](#string-field)): The group number associated with the healthcare plan.
+
+```rb
+puts result.document.inference.prediction.group_number.value
+```
+
+## Issuer 80840
+**issuer80840** ([StringField](#string-field)): The organization that issued the healthcare plan.
+
+```rb
+puts result.document.inference.prediction.issuer80840.value
+```
+
+## Member ID
+**member_id** ([StringField](#string-field)): The unique identifier for the member in the healthcare system.
+
+```rb
+puts result.document.inference.prediction.member_id.value
+```
+
+## Member Name
+**member_name** ([StringField](#string-field)): The name of the member covered by the healthcare plan.
+
+```rb
+puts result.document.inference.prediction.member_name.value
+```
+
+## Payer ID
+**payer_id** ([StringField](#string-field)): The unique identifier for the payer in the healthcare system.
+
+```rb
+puts result.document.inference.prediction.payer_id.value
+```
+
+## RX BIN
+**rx_bin** ([StringField](#string-field)): The BIN number for prescription drug coverage.
+
+```rb
+puts result.document.inference.prediction.rx_bin.value
+```
+
+## RX GRP
+**rx_grp** ([StringField](#string-field)): The group number for prescription drug coverage.
+
+```rb
+puts result.document.inference.prediction.rx_grp.value
+```
+
+## RX PCN
+**rx_pcn** ([StringField](#string-field)): The PCN number for prescription drug coverage.
+
+```rb
+puts result.document.inference.prediction.rx_pcn.value
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/lib/mindee/extraction/ocr_extractor.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Extraction
+    # Generic extractor class
+    class OcrExtractor
+      # Checks for a list of possible matches in a string & returns the index of the first found candidate.
+      # Case & diacritics insensitive.
+      # @param text [String] string to search for matches.
+      # @param str_candidates [Array<String>] array of values to look for
+      # @return [Integer, nil]
+      def self.match_index(text, str_candidates)
+        idx = nil
+        str_candidates.each do |str_candidate|
+          found_idx = remove_accents(text.downcase).index(remove_accents(str_candidate.downcase))
+          idx = found_idx if idx.nil?
+          idx = found_idx if !found_idx.nil? && found_idx >= idx
+        end
+        idx
+      end
+
+      # Normalizes text by removing diacritics.
+      # @param input_str [String] string to handle.
+      # @return [String]
+      def self.remove_accents(input_str)
+        diacritics = [*0x1DC0..0x1DFF, *0x0300..0x036F, *0xFE20..0xFE2F].pack('U*')
+        input_str
+          .unicode_normalize(:nfd)
+          .tr(diacritics, '')
+          .unicode_normalize(:nfc)
+          .scrub
+      end
+
+      # Checks if a given percentage value is within the allowed range
+      # @param value [Integer] The value to check
+      # @param min_rate_percentage [Integer] Minimum allowed rate on the tax.
+      # @param max_rate_percentage [Integer] Maximum allowed rate on the tax.
+      # @return [Boolean]
+      def self.valid_percentage?(value, min_rate_percentage, max_rate_percentage)
+        return false if value.nil?
+
+        value > min_rate_percentage && value < max_rate_percentage
+      end
+
+      # Parses a percentage from a string, and returns it as a float.
+      # Returns nil if candidate isn't a valid percentage.
+      # @param percentage_str [String] String candidate.
+      # @return [Float, nil]
+      def self.parse_percentage(percentage_str)
+        percentage_str.gsub!('%', '')
+        percentage_str.strip
+        percentage_str.gsub!(',', '.')
+        Float(percentage_str.scrub)
+      rescue ArgumentError
+        nil
+      end
+
+      # Parses an amount from a string, and returns it as a float.
+      # Returns nil if candidate isn't a valid amount.
+      # @param amount_str [String] String candidate.
+      # @return [Float, nil]
+      def self.parse_amount(amount_str)
+        cleaned_str = amount_str.gsub(' ', '')
+        cleaned_str = standardize_delimiters(cleaned_str)
+        Float(cleaned_str)
+      rescue ArgumentError
+        nil
+      end
+
+      private
+
+      def self.standardize_delimiters(str)
+        if comma_decimal?(str)
+          str.gsub('.', '').gsub(',', '.')
+        elsif dot_decimal?(str)
+          str.gsub(',', '')
+        else
+          str
+        end
+      end
+
+      def self.comma_decimal?(str)
+        (str.length > 3 && str[-3] == ',') || str[-2] == ','
+      end
+
+      def self.dot_decimal?(str)
+        (str.length > 3 && str[-3] == '.') || str[-2] == '.'
+      end
+
+      # Removes most common currency symbols from string
+      # @param input_string [String] string to remove the symbols from
+      # @return [String]
+      def self.remove_currency_symbols(input_string)
+        # Define an array of common currency symbols
+        currency_symbols = ['$', '€', '£', '¥', '₹', '₽', '฿', '₺', '₴', '₿', '₡', '₮', '₱', '₲', '₪', '₫', '₩', '₵',
+                            '₦', '₢', '₤', '₣', '₧', '₯', '₠', '₶', '₸', '₷', '₼', '₾', '₺', '﹩', '₨', '₹', '＄', '﹫']
+
+        # Iterate over each currency symbol and remove it from the input string
+        currency_symbols.each do |symbol|
+          input_string.gsub!(symbol, '')
+        end
+
+        input_string
+      end
+
+      private_class_method :remove_accents, :match_index, :parse_amount, :parse_percentage, :remove_currency_symbols,
+                           :valid_percentage?, :comma_decimal?, :dot_decimal?, :standardize_delimiters
+    end
+  end
+end