mindee 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0b76bde0354208269f645114e453b15ce48569ae3ce01fd194582f67a2ef6a4
-  data.tar.gz: 96a22bf367165b1c06d93bc90f91ef4c71f16781dd43cb954852ca0343e583df
+  metadata.gz: 729bb9b6e8643c95c194583c4c7e217f9cbdc68149a72125767a2191291142be
+  data.tar.gz: cc2233ca32e0fadaf445e731417238b0fa272865f949fd0c91ef61916f86dfb4
 SHA512:
-  metadata.gz: 00060a15fad08a14dccbde8d29a482ae54af57458e742893cf2ac2b61a66201e7dc098a92cee4c1b6a47877fc2b9db05a391bb50fb448b49aadeeb478ce03047
-  data.tar.gz: 81192f06c2e143162675eb1da1caf93481be8a483d8b1dd4dd6d0f6e0eb8869a27163404f260700d5d1e936bdc6523828f8279c820a424da0d96df4a77f467da
+  metadata.gz: 162501228d7fed6ac0829aefcaae88390d43a91cd7b516a837471964b181fe084f9d200e6db447fb4c3b137c3f93ea801661e75ac151a087702143574b8ee9b6
+  data.tar.gz: 960d67e2a53626d3399628b9190972025df886efe50791dc72e5cb0d327f49c99352c66361ff952912b30288c562d3169d2f67ec49a0f8310ed47b40aeedb11d

data/.gitignore

@@ -42,7 +42,7 @@ build-iPhoneSimulator/
 ## Documentation cache and generated files:
 /.yardoc/
 /_yardoc/
-/doc/
+/docs/_build/
 /rdoc/
 
 ## Environment normalization:

data/.rubocop.yml

@@ -26,7 +26,7 @@ Metrics/BlockLength:
     - '**/*.gemspec'
 
 Metrics/MethodLength:
-  Max: 35
+  Max: 45
 
 Metrics/ClassLength:
   Max: 200
@@ -35,7 +35,7 @@ Metrics/ParameterLists:
   Max: 7
 
 Metrics/AbcSize:
-  Max: 50
+  Max: 60
 
 Style/RegexpLiteral:
   EnforcedStyle: percent_r

data/.yardopts

@@ -0,0 +1,4 @@
+--markup markdown
+--main README.md
+--files docs/ruby-getting-started.md,docs/ruby-invoice-ocr.md,docs/ruby-passport-ocr.md,docs/ruby-receipt-ocr.md
+--output-dir docs/_build

data/CHANGELOG.md

@@ -1,20 +1,41 @@
 # Mindee Ruby API Library Changelog
 
+## v2.0.0 - 2023-01-13
+### ¡Breaking Changes!
+* :sparkles: add improved PDF merge system
+* :boom: it should be up to the user to handle API errors
+* :wastebasket: remove deprecated APIs
+* :recycle: refactor CLI tool
+
+### Additions
+* :sparkles: add support for Invoice v4.1 and Receipt v4.1
+* :sparkles: add EU license plates
+* :sparkles: add shipping containers support
+* :sparkles: add US bank check support
+* :sparkles: add all French documents
+* :memo: Add YARD for generating docs
+* :white_check_mark: add testing on Ruby 3.2
+* :sparkles: allow setting the request timeout from env
+
 ## v1.2.0 - 2022-12-26
 ### Changes
 * :arrow_up: switch to origamindee => adds support for Ruby 3
 
+
 ## v1.1.2 - 2022-12-23
 ### Changes
 * :recycle: use of `append_page` is better for adding pages to a new PDF
 
+
 ## v1.1.1 - 2022-08-08
 ### Fixes
 * :bug: Fix for missing attribute accessor
 
+
 ## v1.1.0 - 2022-08-04
 ### Changes
 * :sparkles: Add support for custom API classification field (#5)
 
+
 ## v1.0.0 - 2022-07-28
 * :tada: First release!

data/README.md

@@ -1,13 +1,10 @@
-[![License: MIT](https://img.shields.io/github/license/mindee/mindee-api-ruby)](https://opensource.org/licenses/MIT)
-[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mindee/mindee-api-ruby/test.yml)](https://github.com/mindee/mindee-api-ruby)
-[![Gem Version](https://img.shields.io/gem/v/mindee)](https://rubygems.org/gems/mindee)
-[![Downloads](https://img.shields.io/gem/dt/mindee.svg)](https://rubygems.org/gems/mindee)
+[![License: MIT](https://img.shields.io/github/license/mindee/mindee-api-ruby)](https://opensource.org/licenses/MIT) [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mindee/mindee-api-ruby/test.yml)](https://github.com/mindee/mindee-api-ruby) [![Gem Version](https://img.shields.io/gem/v/mindee)](https://rubygems.org/gems/mindee) [![Downloads](https://img.shields.io/gem/dt/mindee.svg)](https://rubygems.org/gems/mindee)
 
 # Mindee API Helper Library for Ruby
 Quickly and easily connect to Mindee's API services using Ruby.
 
 ## Requirements
-The following Ruby versions are tested and supported: 2.6, 2.7, 3.0, 3.1
+The following Ruby versions are tested and supported: 2.6, 2.7, 3.0, 3.1, 3.2
 
 ## Quick Start
 Here's the TL;DR of getting started.
@@ -24,25 +21,38 @@ And then execute:
 
     $ bundle install
 
-Or install it yourself as:
+Finally, Ruby away!
 
-    $ gem install mindee
+### Loading a File and Parsing It
 
-Finally, Ruby away!
+#### Global Documents
+```ruby
+require 'mindee'
+
+# Init a new client
+mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-### Off-the-Shelf Document
+# Load a file from disk and parse it
+result = mindee_client.doc_from_path('/path/to/the/file.ext')
+  .parse(Mindee::Prediction::InvoiceV4)
+
+# Print a full summary of the parsed data in RST format
+puts result
+```
+
+#### Region-Specific Documents
 ```ruby
 require 'mindee'
 
-# Init a new client and configure the Invoice API
-mindee_client = Mindee::Client.new(api_key: 'my-api-key').config_invoice
+# Init a new client
+mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
 # Load a file from disk and parse it
-api_response = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse('invoice')
+result = mindee_client.doc_from_path('/path/to/the/file.ext')
+  .parse(Mindee::Prediction::EU::LicensePlateV1)
 
-# Print a brief summary of the parsed data
-puts api_response.document
+# Print a full summary of the parsed data in RST format
+puts result.document
 ```
 
 ### Custom Document (API Builder)
@@ -50,27 +60,40 @@ puts api_response.document
 require 'mindee'
 
 # Init a new client and configure your custom document
-mindee_client = Mindee::Client.new(api_key: 'my-api-key').config_custom_doc(
+mindee_client = Mindee::Client.new(api_key: 'my-api-key').add_endpoint(
   'john',
   'wnine'
 )
 
 # Load a file from disk and parse it
-api_response = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse('wnine')
-
-# Print a brief summary of the parsed data
-puts api_response.document
+result = mindee_client.doc_from_path('/path/to/the/file.ext')
+  .parse(Mindee::Prediction::CustomV1, endpoint_name: 'wnine')
+
+# Print a full summary of the parsed data in RST format
+puts result
+
+# Looping over all prediction values
+result.inference.prediction.fields.each do |field_name, field_data|
+  puts field_name
+  puts field_data.values
+  puts field_data.to_s
+end
 ```
 
 ## Further Reading
 There's more to it than that for those that need more features, or want to
 customize the experience.
 
-All the juicy details are described in the
-**[Official Documentation](https://developers.mindee.com/docs/ruby-getting-started)**.
+- [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)
 
 ## License
 Copyright © Mindee, SA
 
 Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/Rakefile

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'rake'
+require 'rspec/core/rake_task'
+require 'yard'
 
 begin
   require 'bundler/setup'
@@ -11,5 +13,8 @@ end
 
 task default: :spec
 
-require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
+
+YARD::Rake::YardocTask.new do |task|
+  task.files = ['lib/**/*.rb']
+end

data/bin/mindee.rb

@@ -6,28 +6,52 @@ require 'optparse'
 require 'mindee'
 
 DOCUMENTS = {
+  "custom" => {
+    help: "Custom document type from API builder",
+    prediction: Mindee::Prediction::CustomV1,
+  },
   "invoice" => {
     help: 'Invoice',
-    doc_type: Mindee::Client::DOC_TYPE_INVOICE,
+    prediction: Mindee::Prediction::InvoiceV4,
   },
   "receipt" => {
     help: "Expense Receipt",
-    doc_type: Mindee::Client::DOC_TYPE_RECEIPT,
+    prediction: Mindee::Prediction::ReceiptV4,
   },
   "passport" => {
     help: "Passport",
-    doc_type: Mindee::Client::DOC_TYPE_PASSPORT,
+    prediction: Mindee::Prediction::PassportV1,
   },
-  "financial" => {
-    help: "Financial Document (receipt or invoice)",
-    doc_type: Mindee::Client::DOC_TYPE_FINANCIAL,
+  "shipping-container" => {
+    help: "Shipping Container",
+    prediction: Mindee::Prediction::ShippingContainerV1,
   },
-  "custom" => {
-    help: "Custom document type from API builder",
+  "eu-license-plate" => {
+    help: "EU License Plate",
+    prediction: Mindee::Prediction::EU::LicensePlateV1,
+  },
+  "fr-bank-account-details" => {
+    help: "FR Bank Account Details",
+    prediction: Mindee::Prediction::FR::BankAccountDetailsV1,
+  },
+  "fr-carte-vitale" => {
+    help: "FR Carte Vitale",
+    prediction: Mindee::Prediction::FR::CarteVitaleV1,
+  },
+  "fr-id-card" => {
+    help: "FR ID Card",
+    prediction: Mindee::Prediction::FR::IdCardV1,
+  },
+  "us-bank-check" => {
+    help: "US Bank Check",
+    prediction: Mindee::Prediction::US::BankCheckV1,
   },
 }
 
-options = {}
+options = {
+  api_key: '',
+  print_full: false,
+}
 
 def ots_subcommand(command, options)
   OptionParser.new do |opt|
@@ -38,20 +62,20 @@ def ots_subcommand(command, options)
     opt.on('-w', '--with-words', 'Include words in response') do |v|
       options[:include_words] = v
     end
-    opt.on('-C', '--no-cut-pages', "Don't cut document pages") do |v|
-      options[:include_words] = v
+    opt.on('-c', '--cut-pages', "Cut document pages") do |v|
+      options[:cut_pages] = v
     end
   end
 end
 
 def custom_subcommand(options)
   OptionParser.new do |opt|
-    opt.banner = "Usage: custom [options] DOC_TYPE FILE"
+    opt.banner = "Usage: custom [options] ENDPOINT_NAME FILE"
     opt.on('-w', '--with-words', 'Include words in response') do |v|
       options[:include_words] = v
     end
-    opt.on('-C', '--no-cut-pages', "Don't cut document pages") do |v|
-      options[:include_words] = v
+    opt.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|
       options[:api_key] = v
@@ -59,79 +83,64 @@ def custom_subcommand(options)
     opt.on('-v [VERSION]', '--version [VERSION]', 'Model version for the API') do |v|
       options[:version] = v
     end
-    opt.on('-u USER', '--user USER', 'API account name for the endpoint') do |v|
-      options[:user] = v
+    opt.on('-a ACCOUNT_NAME', '--account ACCOUNT_NAME', 'API account name for the endpoint') do |v|
+      options[:account_name] = v
     end
   end
 end
 
-def new_ots_client(options, command)
-  raise_on_error = options[:no_raise_errors].nil? ? true : false
-  mindee_client = Mindee::Client.new(
-    api_key: options[:api_key], raise_on_error: raise_on_error
-  )
-  info = DOCUMENTS[command]
-  mindee_client.send("config_#{info[:doc_type]}")
-end
-
-def new_custom_client(options, doc_type)
-  raise_on_error = options[:no_raise_errors].nil? ? true : false
-  mindee_client = Mindee::Client.new(
-    api_key: options[:api_key], raise_on_error: raise_on_error
-  )
-  mindee_client.config_custom_doc(
-    doc_type,
-    options[:user],
-    version: options[:version] || '1'
-  )
-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('-E', '--no-raise-errors', "raise errors behavior") do |v|
-    options[:no_raise_errors] = true
-    end
+  opt.on('-f', '--full', "Print the full data, including pages") do |v|
+    options[:print_full] = true
+  end
 end
 
-subcommands = {
-  'invoice' => ots_subcommand('invoice', options),
-  'receipt' => ots_subcommand('receipt', options),
-  'passport' => ots_subcommand('passport', options),
-  'financial' => ots_subcommand('financial', options),
-  'custom' => custom_subcommand(options),
-}
-
-
-begin
-  global_parser.order!
-  command = ARGV.shift
-  subcommands[command].order!
-rescue NoMethodError => e
+global_parser.order!
+command = ARGV.shift
+if command == 'custom'
+  custom_subcommand(options).order!
+elsif DOCUMENTS.keys.include? command || ''
+  ots_subcommand(command, options).order!
+else
   $stderr.puts global_parser
   exit(1)
 end
 
+mindee_client = Mindee::Client.new(api_key: options[:api_key])
+
 if command == 'custom'
   if ARGV.length != 2
-    $stderr.puts "The 'custom' command requires both DOC_TYPE and FILE arguments."
+    $stderr.puts "The 'custom' command requires both ENDPOINT_NAME and FILE arguments."
     exit(1)
   end
   doc_type = ARGV[0]
   file_path = ARGV[1]
-  mindee_client = new_custom_client(options, doc_type)
+  mindee_client.add_endpoint(
+    options[:account_name], doc_type, version: options[:version] || '1',
+  )
 else
   if ARGV.length != 1
     $stderr.puts 'No file specified.'
     exit(1)
   end
-  mindee_client = new_ots_client(options, command)
-  doc_type = DOCUMENTS[command][:doc_type]
+  doc_type = ''
   file_path = ARGV[0]
 end
 
-cut_pages = options[:no_cut_pages].nil? ? false : true
-doc = mindee_client.doc_from_path(file_path, cut_pages: cut_pages)
-puts doc.parse(doc_type).document
+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
+doc = mindee_client.doc_from_path(file_path)
+result = doc.parse(DOCUMENTS[command][:prediction], endpoint_name: doc_type, page_options: page_options)
+if options[:print_full]
+  puts result
+else
+  puts result.inference.prediction
+end

data/docs/ruby-api-builder.md

@@ -0,0 +1,131 @@
+The Ruby  OCR SDK supports [custom-built API](https://developers.mindee.com/docs/build-your-first-document-parsing-api)
+from the API Builder.
+
+If your document isn't covered by one of Mindee's Off-the-Shelf APIs, you can create your own API using the
+[API Builder](https://developers.mindee.com/docs/overview).
+
+For the following examples, we are using our own [W9s custom API](https://developers.mindee.com/docs/w9-forms-ocr)
+created with the [API Builder](https://developers.mindee.com/docs/overview).
+
+> 📘 **Info**
+>
+> We used a data model that may be different from yours. To modify this to your own custom API,
+> change the `config_custom_doc` call with your own parameters.
+
+```ruby
+require 'mindee'
+
+# Init a new client and configure your custom document
+mindee_client = Mindee::Client.new(
+  api_key: 'my-api-key', # optional, can be set in environment
+).config_custom_doc(
+  'wsnine',
+  'john',
+  version: '1.1' # optional, if not set, use the latest version of the model
+)
+
+# Load a file from disk and parse it
+w9_data = mindee_client.doc_from_path('/path/to/file.pdf').parse('wsnine')
+
+# Print a brief summary of the parsed data
+puts w9_data.document.to_s
+```
+
+If the `version` argument is set, you'll be required to update it every time a new model is trained.
+This is probably not needed for development but essential for production use.
+
+## Parsing Documents
+The client calls the `parse` method when parsing your custom document, which will return an object that you can send to the API.
+The document type must be specified when calling the parse method.
+
+```ruby
+result = mindee_client.doc_from_path('/path/to/custom_file').parse('wsnine')
+puts result
+```
+
+> 📘 **Info**
+>
+> If your custom document has the same name as an [off-the-shelf APIs](https://developers.mindee.com/docs/what-is-off-the-shelf-api) document,
+> you **must** specify your account name when calling the `parse` method:
+
+```ruby
+mindee_client = Mindee::Client.new.config_custom_doc(
+  'receipt',
+  'john'
+)
+
+result = mindee_client.doc_from_path('/path/to/receipt.jpg')
+  .parse('receipt', username: 'john')
+```
+
+## Document Fields
+All the fields defined in the API builder when creating your custom document are available.
+
+In custom documents, each field will hold an array of all the words in the document which are related to that field.
+Each word is an object that has the text content, geometry information, and confidence score.
+
+Value fields can be accessed either via the `fields` attribute, or as their own attributes set at run-time.
+
+Classification fields can be accessed either via the `classifications` attribute, or as their own attributes set at run-time.
+
+> 📘 **Info**
+>
+> Both document level and page level objects work in the same way.
+
+### Run-time Attributes
+Individual field values can be accessed simply by using the field's API name, in the examples below we'll use the `address` field.
+
+```ruby
+# raw data, list of each word object
+puts w9_data.document.address.values
+
+# list of all values
+puts w9_data.document.address.contents_list
+
+# default string representation
+puts w9_data.document.address.to_s
+
+# custom string representation
+puts w9_data.document.address.contents_str(separator: '_')
+```
+
+### Fields property
+In addition to accessing a value field directly, it's possible to access it through the `fields` attribute.
+It's a hashmap with the following structure:
+* key: the API name of the field, as a `symbol`
+* value: a `ListField` object which has a `values` attribute, containing a list of all values found for the field.
+
+```ruby
+# raw data, list of each word object
+puts w9_data.document.fields[:address].values
+```
+
+This makes it simple to iterate over all the fields:
+```ruby
+w9_data.document.fields.each do |name, info|
+  puts name
+  puts info.values
+end
+```
+
+### Classifications property
+In addition to accessing a classification field directly, it's possible to access it through the `classifications` attribute.
+It's a hashmap with the following structure:
+* key: the API name of the field, as a `symbol`
+* value: a `ClassificationField` object which has a `value` attribute, containing a string representation of the detected classification.
+
+```ruby
+# raw data, list of each word object
+puts w9_data.document.classifications[:doc_type].value
+```
+
+This makes it simple to iterate over all the fields:
+```ruby
+w9_data.document.classifications.each do |name, info|
+  puts name
+  puts info.value
+end
+```
+
+## Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)