mindee 3.1.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b59351d1529520bbdad3ef1757dc9f543662b6bc227338c2ffef15c515768e2e
-  data.tar.gz: 2cb0ee0f94b7ee2ce640b5ce7598e9e23a5e4eafaef293c748d2eaf9208da040
+  metadata.gz: 3ab7abbf2686b67f4330ceb018dc5de8b799d567d586072199f22dfcb12b647d
+  data.tar.gz: 15d885b0fa5e42cf84a1ca6f4238f0c1681bb4c3587fbdf8cd9b48f69850a1f4
 SHA512:
-  metadata.gz: f7e20639bbd253793cc20b2ab2ccf0f3194badc727b62ee8f2a34022994fbaf317f7c16e69e31a512cb3457d9e11a116894d2bd828a820924df4de1ae7ec72a2
-  data.tar.gz: fb699dd16576182f16e2452b796a46badac444a210d4f4f4ad096e696301940d8c85cc21aad6962b111d27b16d31a483ccacf899b6f3352f1f975e7720ec0075
+  metadata.gz: 0036d0f5b668d81a1fb602689fc33d98e6ff02a03175b219f7c541689d27a4fb76123982610d979b89f97f074d3fc202effa5f3d00ac9da905d99afe20ef0beb
+  data.tar.gz: dc4d2bd7147c6c0d4d589642d0d6b6a343fdfc5fc305e5d03fe1628dd013b70679b5185fd531015957a998ae9c930d570f537e352d7899ff783945179c480470

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Mindee Ruby API Library Changelog
 
+## v3.2.0 - 2023-09-15
+### Changes
+* :sparkles: add support for Multi Receipts Detector V1
+* :sparkles: add support for Barcode Reader V1
+* :sparkles: add support for W9 V1
+* :sparkles: add support for FR ID Card V2
+* :sparkles: add support for async in CLI
+* :sparkles: add support for async auto-polling
+* :sparkles: add direct access to `raw_http` response
+* :memo: upgrade reference & guide documentation
+* :test_tube: **EXPERIMENTAL** add PDF repair option
+
+### Fixes
+* :bug: fix display issues with `PositionField`
+
+
 ## v3.1.1 - 2023-08-10
 ### Fixes
 * :bug: fixed non-pdf files being improperly handled by Ruby requests

data/README.md

@@ -18,8 +18,9 @@ gem 'mindee'
 ```
 
 And then execute:
-
-    $ bundle install
+```sh
+bundle install
+```
 
 Finally, Ruby away!
 
@@ -43,6 +44,28 @@ result = mindee_client.parse(
 puts result.document
 ```
 
+**Note:** Files can also be loaded from:
+
+A URL (`https`):
+```rb
+input_source = mindee_client.source_from_url("https://my-url")
+```
+
+A bytes input stream:
+```rb
+input_source = mindee_client.source_from_bytes('/path/to/the/file.ext', "name-of-my-file.ext")
+```
+
+A base64 encoded string:
+```rb
+input_source = mindee_client.source_from_b64string('/path/to/the/file.ext', "name-of-my-file.ext")
+```
+
+A ruby `file` object:
+```rb
+input_source = mindee_client.source_from_file(input_file, "name-of-my-file.ext")
+```
+
 #### Region-Specific Documents
 ```ruby
 require 'mindee'
@@ -93,15 +116,42 @@ result.document.inference.prediction.fields.each do |field_name, field_data|
 end
 ```
 
+## CLI Tool
+
+A command-line interface tool is available to quickly test documents:
+```sh
+ruby ./bin/mindee.rb invoice path/to/your/file.ext
+```
+
+
+Using the ruby bundler:
+```sh
+bundle exec ruby ./bin/mindee.rb invoice path/to/your/file.ext
+```
+
 ## Further Reading
 There's more to it than that for those that need more features, or want to
 customize the experience.
 
-* [Ruby Overview](https://developers.mindee.com/docs/ruby-getting-started)
-* [Ruby Custom APIs OCR](https://developers.mindee.com/docs/ruby-api-builder)
-* [Ruby invoices OCR](https://developers.mindee.com/docs/ruby-invoice-ocr)
-* [Ruby receipts OCR](https://developers.mindee.com/docs/ruby-receipt-ocr)
-* [Ruby passports OCR](https://developers.mindee.com/docs/ruby-passport-ocr)
+* [Ruby Overview](https://developers.mindee.com/docs/getting-started-ocr-ruby)
+* [Custom OCR Ruby](https://developers.mindee.com/docs/api-builder-ocr-ruby)
+* [Invoice OCR Ruby](https://developers.mindee.com/docs/invoice-ocr-ruby)
+* [Financial Document OCR Ruby](https://developers.mindee.com/docs/financial-document-ocr-ruby)
+* [Passport OCR Ruby](https://developers.mindee.com/docs/passport-ocr-ruby)
+* [Proof of Address OCR Ruby](https://developers.mindee.com/docs/proof-of-address-ocr-ruby)
+* [Receipt OCR Ruby](https://developers.mindee.com/docs/receipt-ocr-ruby)
+* [EU License Plate OCR Ruby](https://developers.mindee.com/docs/eu-license-plate-ocr-ruby)
+* [FR Bank Account Details OCR Ruby](https://developers.mindee.com/docs/fr-bank-account-details-ocr-ruby)
+* [FR Carte Vitale OCR Ruby](https://developers.mindee.com/docs/fr-carte-vitale-ocr-ruby)
+* [FR ID Card OCR Ruby](https://developers.mindee.com/docs/fr-id-card-ocr-ruby)
+* [US Bank Check OCR Ruby](https://developers.mindee.com/docs/us-bank-check-ocr-ruby)
+* [US Driver License OCR Ruby](https://developers.mindee.com/docs/us-driver-license-ocr-ruby)
+* [US W9 API Ruby](https://developers.mindee.com/docs/us-w9-api-ruby)
+* [Barcode Reader API Ruby](https://developers.mindee.com/docs/barcode-reader-api-ruby)
+* [Cropper API Ruby](https://developers.mindee.com/docs/cropper-api-ruby)
+* [Invoice Splitter API Ruby](https://developers.mindee.com/docs/invoice-splitter-api-ruby)
+* [Multi Receipts Detector API Ruby](https://developers.mindee.com/docs/multi-receipts-detector-api-ruby)
+
 
 You can also take a look at the
 [Reference Documentation](https://mindee.github.io/mindee-api-ruby/).

data/bin/mindee.rb

@@ -1,149 +1,226 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'optparse'
-
 require 'mindee'
 
 DOCUMENTS = {
   "custom" => {
-    help: "Custom document type from API builder",
-    prediction: Mindee::Product::Custom::CustomV1,
+    description: "Custom document type from API builder",
+    doc_class: Mindee::Product::Custom::CustomV1,
+    sync: true,
+    async: false,
   },
   "proof-of-address" => {
-    help: 'Proof of Address',
-    prediction: Mindee::Product::ProofOfAddress::ProofOfAddressV1,
+    description: 'Proof of Address',
+    doc_class: Mindee::Product::ProofOfAddress::ProofOfAddressV1,
+    sync: true,
+    async: false,
+  },
+  "cropper" => {
+    description: 'Cropper',
+    doc_class: Mindee::Product::Cropper::CropperV1,
+    sync: true,
+    async: false,
   },
   "financial-document" => {
-    help: 'Financial Document',
-    prediction: Mindee::Product::FinancialDocument::FinancialDocumentV1,
+    description: 'Financial Document',
+    doc_class: Mindee::Product::FinancialDocument::FinancialDocumentV1,
+    sync: true,
+    async: false,
   },
   "invoice" => {
-    help: 'Invoice',
-    prediction: Mindee::Product::Invoice::InvoiceV4,
+    description: 'Invoice',
+    doc_class: Mindee::Product::Invoice::InvoiceV4,
+    sync: true,
+    async: false,
   },
   "receipt" => {
-    help: "Expense Receipt",
-    prediction: Mindee::Product::Receipt::ReceiptV5,
+    description: "Expense Receipt",
+    doc_class: Mindee::Product::Receipt::ReceiptV5,
+    sync: true,
+    async: false,
   },
   "passport" => {
-    help: "Passport",
-    prediction: Mindee::Product::Passport::PassportV1,
+    description: "Passport",
+    doc_class: Mindee::Product::Passport::PassportV1,
+    sync: true,
+    async: false,
   },
   "eu-license-plate" => {
-    help: "EU License Plate",
-    prediction: Mindee::Product::EU::LicensePlate::LicensePlateV1,
+    description: "EU License Plate",
+    doc_class: Mindee::Product::EU::LicensePlate::LicensePlateV1,
+    sync: true,
+    async: false,
   },
   "fr-bank-account-details" => {
-    help: "FR Bank Account Details",
-    prediction: Mindee::Product::FR::BankAccountDetails::BankAccountDetailsV1,
+    description: "FR Bank Account Details",
+    doc_class: Mindee::Product::FR::BankAccountDetails::BankAccountDetailsV2,
+    sync: true,
+    async: false,
   },
   "fr-carte-vitale" => {
-    help: "FR Carte Vitale",
-    prediction: Mindee::Product::FR::CarteVitale::CarteVitaleV1,
+    description: "FR Carte Vitale",
+    doc_class: Mindee::Product::FR::CarteVitale::CarteVitaleV1,
+    sync: true,
+    async: false,
   },
   "fr-id-card" => {
-    help: "FR ID Card",
-    prediction: Mindee::Product::FR::IdCard::IdCardV1,
+    description: "FR ID Card",
+    doc_class: Mindee::Product::FR::IdCard::IdCardV2,
+    sync: true,
+    async: false,
   },
   "us-bank-check" => {
-    help: "US Bank Check",
-    prediction: Mindee::Product::US::BankCheck::BankCheckV1,
+    description: "US Bank Check",
+    doc_class: Mindee::Product::US::BankCheck::BankCheckV1,
+    sync: true,
+    async: false,
+  },
+  "us-driver-license" => {
+    description: "US Driver License",
+    doc_class: Mindee::Product::US::DriverLicense::DriverLicenseV1,
+    sync: true,
+    async: false,
+  },
+  "us-w9" => {
+    description: "US W9 Form",
+    doc_class: Mindee::Product::US::W9::W9V1,
+    sync: true,
+    async: false
   },
   "invoice-splitter" => {
-    help: "US Bank Check",
-    prediction: Mindee::Product::InvoiceSplitter::InvoiceSplitterV1,
+    description: "US Bank Check",
+    doc_class: Mindee::Product::InvoiceSplitter::InvoiceSplitterV1,
+    sync: false,
+    async: true,
   },
 }
 
-options = {
-  api_key: '',
-  print_full: false,
+options = {}
+DEFAULT_CUTTING = {
+  page_indexes: [0, 1, 2, 3, 4],
+  operation: :KEEP_ONLY,
+  on_min_pages: 0,
 }
 
-def ots_subcommand(command, options)
-  OptionParser.new do |opt|
-    opt.banner = "Usage: #{command} [options] FILE"
-    opt.on('-k [KEY]', '--key [KEY]', 'API key for the endpoint') do |v|
-      options[:api_key] = v
-    end
-    opt.on('-w', '--all-words', 'Include words in response') do |v|
-      options[:all_words] = v
-    end
-    opt.on('-c', '--cut-pages', "Cut document pages") do |v|
-      options[:cut_pages] = v
-    end
+# Initializes custom-specific options
+# @param cli_parser [OptionParser]
+def custom_subcommand(cli_parser)
+  cli_parser.on('-v [VERSION]', '--version [VERSION]', 'Model version for the API') do |v|
+    options[:version] = v
+  end
+  cli_parser.on('-a ACCOUNT_NAME', '--account ACCOUNT_NAME', 'API account name for the endpoint') do |v|
+    options[:account_name] = v
   end
 end
 
-def custom_subcommand(options)
-  OptionParser.new do |opt|
-    opt.banner = "Usage: custom [options] ENDPOINT_NAME FILE"
-    opt.on('-w', '--all-words', 'Include words in response') do |v|
+product_parser = {}
+DOCUMENTS.each do |doc_key, doc_value|
+  product_parser[doc_key] = OptionParser.new do | opts |
+    opts.on('-w', '--all-words', 'Include words in response') do |v|
       options[:all_words] = v
     end
-    opt.on('-c', '--cut-pages', "Don't cut document pages") do |v|
+    opts.on('-c', '--cut-pages', "Don't cut document pages") do |v|
       options[:cut_pages] = v
     end
-    opt.on('-k [KEY]', '--key [KEY]', 'API key for the endpoint') do |v|
+    opts.on('-k [KEY]', '--key [KEY]', 'API key for the endpoint') do |v|
       options[:api_key] = v
     end
-    opt.on('-v [VERSION]', '--version [VERSION]', 'Model version for the API') do |v|
-      options[:version] = v
+    opts.on('-f', '--full', "Print the full data, including pages") do |v|
+      options[:print_full] = true
+    end
+    opts.on('-F', '--fix-pdf', "Attempts to fix broken PDF files before sending them to the server.") do |v|
+      options[:fix_pdf] = true
     end
-    opt.on('-a ACCOUNT_NAME', '--account ACCOUNT_NAME', 'API account name for the endpoint') do |v|
-      options[:account_name] = v
+    if (doc_key != 'custom')
+      opts.banner = "Product: #{doc_value[:description]}. \nUsage: mindee.rb #{doc_key} [options] file"
+    else
+      opts.banner = "#{doc_value[:description]}. \nUsage: mindee.rb custom [options] endpoint_name file"
+      custom_subcommand(opts)
+    end
+    if doc_value[:async]
+      if doc_value[:sync]
+        opts.on("-A", "--async", "Call asynchronously") do |v|
+          options[:parse_async] = v
+        end
+      end
     end
   end
 end
 
-global_parser = OptionParser.new do |opt|
-  opt.banner = "Usage: #{$PROGRAM_NAME} [options] subcommand [options] FILE"
-  opt.separator('')
-  opt.separator("subcommands: #{DOCUMENTS.keys.join(', ')}")
-  opt.separator('')
-  opt.on('-f', '--full', "Print the full data, including pages") do |v|
-    options[:print_full] = true
-  end
+global_parser = OptionParser.new do | opts |
+  opts.banner = "Usage: mindee.rb product [options] file"
+  opts.separator "Available products:"
+  opts.separator "  #{DOCUMENTS.keys.join("\n  ")}"
 end
 
-global_parser.order!
 command = ARGV.shift
+if !DOCUMENTS.has_key?(command)
+  abort(global_parser.help)
+end
+doc_class = DOCUMENTS[command][:doc_class]
+product_parser[command].parse!
+
 if command == 'custom'
-  custom_subcommand(options).order!
-elsif DOCUMENTS.keys.include? command || ''
-  ots_subcommand(command, options).order!
+  if ARGV.length < 2
+    $stderr.puts "The 'custom' command requires both ENDPOINT_NAME and file arguments."
+    abort(product_parser[command].help)
+  end
+  endpoint_name = ARGV[0]
+  options[:file_path] = ARGV[1]
 else
-  $stderr.puts global_parser
-  exit(1)
+  if ARGV.length < 1
+    $stderr.puts "file missing"
+    abort(product_parser[command].help)
+  end
+  endpoint_name = nil
+  options[:file_path] = ARGV[0]
 end
 
 mindee_client = Mindee::Client.new(api_key: options[:api_key])
+if (options[:file_path].start_with?("https://"))
+  input_source = mindee_client.source_from_url(options[:file_path])
+else
+  input_source = mindee_client.source_from_path(options[:file_path], fix_pdf: options[:fix_pdf])
+end
 
 if command == 'custom'
-  if ARGV.length != 2
-    $stderr.puts "The 'custom' command requires both ENDPOINT_NAME and FILE arguments."
-    exit(1)
-  end
-  doc_type = ARGV[0]
-  file_path = ARGV[1]
+  endpoint_name = 'endpoint_name'
+  custom_endpoint = mindee_client.create_endpoint(
+    account_name: endpoint_name,
+    endpoint_name: options[:account_name],
+    endpoint_version: options[:endpoint_version].nil? ? "1" : options[:endpoint_version]
+  )
 else
-  if ARGV.length != 1
-    $stderr.puts 'No file specified.'
-    exit(1)
-  end
-  doc_type = ''
-  file_path = ARGV[0]
+  custom_endpoint = nil
 end
 
-default_cutting = {
-  page_indexes: [0, 1, 2, 3, 4],
-  operation: :KEEP_ONLY,
-  on_min_pages: 0,
-}
 page_options = options[:cut_pages].nil? ? nil : default_cutting
-input_source = mindee_client.source_from_path(file_path)
-result = mindee_client.parse(input_source, DOCUMENTS[command][:prediction], page_options: page_options)
+if options[:parse_async].nil?
+  if !DOCUMENTS[command][:sync]
+    options[:parse_async] = true
+  else
+    options[:parse_async] = false
+  end
+end
+if options[:parse_async]
+  result = mindee_client.enqueue_and_parse(
+    input_source,
+    DOCUMENTS[command][:doc_class],
+    endpoint: custom_endpoint,
+    page_options: page_options,
+  )
+else
+  result = mindee_client.parse(
+    input_source,
+    DOCUMENTS[command][:doc_class],
+    endpoint: custom_endpoint,
+    page_options: page_options,
+  )
+end
+
 if options[:print_full]
   puts result.document
 else

data/docs/bank_account_details_v2.md

@@ -0,0 +1,137 @@
+---
+title: FR Bank Account Details OCR Ruby
+---
+The Ruby OCR SDK supports the [Bank Account Details API](https://platform.mindee.com/mindee/bank_account_details).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/bank_account_details/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Bank Account Details sample](https://github.com/mindee/client-lib-test-data/blob/main/products/bank_account_details/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.parse(
+  input_source,
+  Mindee::Product::FR::BankAccountDetails::BankAccountDetailsV2
+)
+
+# 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: bc8f7265-8dab-49fe-810c-d50049605578
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/bank_account_details v2.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Account Holder's Names: MME HEGALALDIA L ENVOL
+:Basic Bank Account Number:
+  :Bank Code: 13335
+  :Branch Code: 00040
+  :Key: 06
+  :Account Number: 08932891361
+:IBAN: FR7613335000400893289136106
+:SWIFT Code: CEPAFRPP333
+
+Page Predictions
+================
+
+Page 0
+------
+:Account Holder's Names: MME HEGALALDIA L ENVOL
+:Basic Bank Account Number:
+  :Bank Code: 13335
+  :Branch Code: 00040
+  :Key: 06
+  :Account Number: 08932891361
+:IBAN: FR7613335000400893289136106
+:SWIFT Code: CEPAFRPP333
+```
+
+# 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 or not 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.
+
+### 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.
+
+### Basic Bank Account Number Field
+Full extraction of BBAN, including: branch code, bank code, account and key.
+
+A `BankAccountDetailsV2Bban` implements the following attributes:
+
+* `bban_bank_code` (String): The BBAN bank code outputted as a string.
+* `bban_branch_code` (String): The BBAN branch code outputted as a string.
+* `bban_key` (String): The BBAN key outputted as a string.
+* `bban_number` (String): The BBAN Account number outputted as a string.
+
+# Attributes
+The following fields are extracted for Bank Account Details V2:
+
+## Account Holder's Names
+**account_holders_names** ([StringField](#string-field)): Full extraction of the account holders names.
+
+```rb
+puts result.document.inference.prediction.account_holders_names.value
+```
+
+## Basic Bank Account Number
+**bban** ([BankAccountDetailsV2Bban](#basic-bank-account-number-field)): Full extraction of BBAN, including: branch code, bank code, account and key.
+
+```rb
+puts result.document.inference.prediction.bban.value
+```
+
+## IBAN
+**iban** ([StringField](#string-field)): Full extraction of the IBAN number.
+
+```rb
+puts result.document.inference.prediction.iban.value
+```
+
+## SWIFT Code
+**swift_code** ([StringField](#string-field)): Full extraction of the SWIFT code.
+
+```rb
+puts result.document.inference.prediction.swift_code.value
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)