mindee 2.2.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e72f138a729f4c2296fb6fa1913ae54b55b7e25e49134d20bc91c7a6a90c7ae
-  data.tar.gz: cf14c3229afc27d75017c2a184ef661fafdae38d22af046d5aed4651ad3aeb31
+  metadata.gz: c81762ec2e42847a182b6b864355ba0268ad22995c24b361e54fd5380f8191f3
+  data.tar.gz: 771736fbe9d28b5d7a91c7cfee9a687da116f176c8226f866ab8bf175cab7b7f
 SHA512:
-  metadata.gz: 89dc112d3507a28af8fbc91f38715cc504772fbd4a47808b36ee138da1368966bad4a8629f4cc4de2a70a381635f599fe8f7105c11d432879bb949b17b1c3304
-  data.tar.gz: 24cd2c56da98a224aa6193d2bb0ba3d2dc7d0b397efcc7e2cd720d4e9d80a93c26b5adcc085ed1dd28d36e2619eb30cd86804ecb69dc3fc9901712cc830236ba
+  metadata.gz: 145a65bda997dc06a3ffafee6123d38195f66e6907c74097efca1a7d5bec9c8d70c041a7a58428e24be22a4850ff36e994a92024252735a815180032fe89f7a5
+  data.tar.gz: 605b1a9b1ffa2c0948581632eeca05e6462ce7f2280281740255183659648c7feb56ace62ec466cb69716f199a6a6467d4c5f1fa27e304fd83899b9a4dcfb2d9

data/.gitignore

@@ -18,6 +18,7 @@
 _test.rb
 /vendor
 /mindee-*/
+local-test
 
 # Used by dotenv library to load environment variables.
 .env

data/.rubocop.yml

@@ -6,6 +6,8 @@ AllCops:
     - 'tmp/**/*'
     - '.git/**/*'
     - 'bin/*'
+    - _test.rb
+
   TargetRubyVersion: 2.6
   SuggestExtensions: false
 

data/.yardopts

@@ -1,3 +1,4 @@
 --markup markdown
 --main README.md
+--fail-on-warning
 --output-dir docs/_build

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Mindee Ruby API Library Changelog
 
+## v3.0.0 - 2023-06-29
+### ¡Breaking Changes!
+
+* :boom: update `Client` creation & document upload
+* :boom: update custom `Endpoint` creation syntax
+* :art: improve product class syntax & structure
+* :recycle: harmonize naming with other client libraries
+* :art: moved most parsing modules into their own respective modules
+* :art: separated common, standard & custom parsing features into their own modules
+
+### Changes
+
+* :sparkles: add support for asynchronous endpoints
+* :sparkles: add support for Invoice Splitter V1
+* :sparkles: add support for OCR Full-text parsing on compatible APIs
+* :sparkles: add support for FR Bank Account Details V2
+* :sparkles: allow for the implementation of pages to differ from main document
+* :sparkles: add url input source
+* :coffin: remove Shipping Containers
+* :recycle: moved all products into the `Product` module (from `Parsing`)
+* :recycle: better implementation of geometric operations
+* :pencil2: document all previously non-documented class
+* :recycle: match file hierarchy with module nesting
+* :recycle: rewrite tutorials to match new syntax
+
+### Fixes
+
+* :bug: fix: pages now use the proper `orientation` property
+* :zap: optimize: only a single endpoint is now created on document upload
+
+
 ## v2.2.1 - 2023-05-22
 ### Fixes
 * :bug: added base attribute to tax field

data/README.md

@@ -32,12 +32,15 @@ require 'mindee'
 # Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::InvoiceV4)
+# Load a file from disk
+input_source = mindee_client.source_from_path('/path/to/the/file.ext')
+result = mindee_client.parse(
+  input_source,
+  Mindee::Product::Invoice::InvoiceV4
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 ```
 
 #### Region-Specific Documents
@@ -47,12 +50,16 @@ require 'mindee'
 # Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::EU::LicensePlateV1)
+# Load a file from disk
+input_source = mindee_client.source_from_path('/path/to/the/file.ext')
+
+result = mindee_client.parse(
+  input_source,
+  Mindee::Product::EU::LicensePlate::LicensePlateV1
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 ```
 
 ### Custom Document (API Builder)
@@ -60,20 +67,26 @@ puts result
 require 'mindee'
 
 # Init a new client and configure your custom document
-mindee_client = Mindee::Client.new(api_key: 'my-api-key').add_endpoint(
-  'my-account',
-  'my-endpoint'
+mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+endpoint = mindee_client.create_endpoint(
+  endpoint_name: 'my-endpoint',
+  account_name: 'my-account'
 )
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::CustomV1, endpoint_name: 'my-endpoint')
+# Load a file from disk
+input_source = mindee_client.source_from_path('/path/to/the/file.ext')
+
+result = mindee_client.parse(
+  input_source,
+  Mindee::Product::Custom::CustomV1,
+  endpoint: endpoint
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 
 # Looping over all prediction values
-result.inference.prediction.fields.each do |field_name, field_data|
+result.document.inference.prediction.fields.each do |field_name, field_data|
   puts field_name
   puts field_data.values
   puts field_data.to_s

data/bin/mindee.rb

@@ -8,51 +8,51 @@ require 'mindee'
 DOCUMENTS = {
   "custom" => {
     help: "Custom document type from API builder",
-    prediction: Mindee::Prediction::CustomV1,
+    prediction: Mindee::Product::Custom::CustomV1,
   },
   "proof-of-address" => {
     help: 'Proof of Address',
-    prediction: Mindee::Prediction::ProofOfAddressV1,
+    prediction: Mindee::Product::ProofOfAddress::ProofOfAddressV1,
   },
   "financial-document" => {
     help: 'Financial Document',
-    prediction: Mindee::Prediction::FinancialDocumentV1,
+    prediction: Mindee::Product::FinancialDocument::FinancialDocumentV1,
   },
   "invoice" => {
     help: 'Invoice',
-    prediction: Mindee::Prediction::InvoiceV4,
+    prediction: Mindee::Product::Invoice::InvoiceV4,
   },
   "receipt" => {
     help: "Expense Receipt",
-    prediction: Mindee::Prediction::ReceiptV5,
+    prediction: Mindee::Product::Receipt::ReceiptV5,
   },
   "passport" => {
     help: "Passport",
-    prediction: Mindee::Prediction::PassportV1,
-  },
-  "shipping-container" => {
-    help: "Shipping Container",
-    prediction: Mindee::Prediction::ShippingContainerV1,
+    prediction: Mindee::Product::Passport::PassportV1,
   },
   "eu-license-plate" => {
     help: "EU License Plate",
-    prediction: Mindee::Prediction::EU::LicensePlateV1,
+    prediction: Mindee::Product::EU::LicensePlate::LicensePlateV1,
   },
   "fr-bank-account-details" => {
     help: "FR Bank Account Details",
-    prediction: Mindee::Prediction::FR::BankAccountDetailsV1,
+    prediction: Mindee::Product::FR::BankAccountDetails::BankAccountDetailsV1,
   },
   "fr-carte-vitale" => {
     help: "FR Carte Vitale",
-    prediction: Mindee::Prediction::FR::CarteVitaleV1,
+    prediction: Mindee::Product::FR::CarteVitale::CarteVitaleV1,
   },
   "fr-id-card" => {
     help: "FR ID Card",
-    prediction: Mindee::Prediction::FR::IdCardV1,
+    prediction: Mindee::Product::FR::IdCard::IdCardV1,
   },
   "us-bank-check" => {
     help: "US Bank Check",
-    prediction: Mindee::Prediction::US::BankCheckV1,
+    prediction: Mindee::Product::US::BankCheck::BankCheckV1,
+  },
+  "invoice-splitter" => {
+    help: "US Bank Check",
+    prediction: Mindee::Product::InvoiceSplitter::InvoiceSplitterV1,
   },
 }
 
@@ -67,8 +67,8 @@ def ots_subcommand(command, options)
     opt.on('-k [KEY]', '--key [KEY]', 'API key for the endpoint') do |v|
       options[:api_key] = v
     end
-    opt.on('-w', '--with-words', 'Include words in response') do |v|
-      options[:include_words] = v
+    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
@@ -79,8 +79,8 @@ end
 def custom_subcommand(options)
   OptionParser.new do |opt|
     opt.banner = "Usage: custom [options] ENDPOINT_NAME FILE"
-    opt.on('-w', '--with-words', 'Include words in response') do |v|
-      options[:include_words] = v
+    opt.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|
       options[:cut_pages] = v
@@ -127,9 +127,6 @@ if command == 'custom'
   end
   doc_type = ARGV[0]
   file_path = ARGV[1]
-  mindee_client.add_endpoint(
-    options[:account_name], doc_type, version: options[:version] || '1',
-  )
 else
   if ARGV.length != 1
     $stderr.puts 'No file specified.'
@@ -145,10 +142,10 @@ default_cutting = {
   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)
+input_source = mindee_client.source_from_path(file_path)
+result = mindee_client.parse(input_source, DOCUMENTS[command][:prediction], page_options: page_options)
 if options[:print_full]
-  puts result
+  puts result.document
 else
-  puts result.inference.prediction
+  puts result.document.inference.prediction
 end

data/docs/code_samples/bank_account_details_v1.txt

@@ -3,12 +3,17 @@ require 'mindee'
 # Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::FR::BankAccountDetailsV1)
+# 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::BankAccountDetailsV1
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 
 # Print the document-level parsed data
-# puts result.inference.prediction
+# puts result.document.inference.prediction

data/docs/code_samples/bank_account_details_v2.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.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

data/docs/code_samples/bank_check_v1.txt

@@ -3,12 +3,17 @@ require 'mindee'
 # Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::US::BankCheckV1)
+# 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::US::BankCheck::BankCheckV1
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 
 # Print the document-level parsed data
-# puts result.inference.prediction
+# puts result.document.inference.prediction

data/docs/code_samples/carte_vitale_v1.txt

@@ -3,12 +3,17 @@ require 'mindee'
 # Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::FR::CarteVitaleV1)
+# 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::CarteVitale::CarteVitaleV1
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 
 # Print the document-level parsed data
-# puts result.inference.prediction
+# puts result.document.inference.prediction

data/docs/code_samples/custom_v1.txt

@@ -1,23 +1,32 @@
 require 'mindee'
 
-# Init a new client and configure your custom document
-mindee_client = Mindee::Client.new(api_key: 'my-api-key').add_endpoint(
-  'my-account',
-  'my-endpoint'
+# 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')
+
+# Initialize a custom endpoint for this product
+custom_endpoint = mindee_client.create_endpoint(
+  account_name: 'my-account',
+  endpoint_name: 'my-endpoint'
 )
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::CustomV1, endpoint_name: 'my-endpoint')
+# Parse the file
+result = mindee_client.parse(
+  input_source,
+  Mindee::Product::Custom::CustomV1,
+  endpoint: custom_endpoint
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 
 # Print the document-level parsed data
-# puts result.inference.prediction
+# puts result.document.inference.prediction
 
 # Looping over all prediction values
-result.inference.prediction.fields.each do |field_name, field_data|
+result.document.inference.prediction.fields.each do |field_name, field_data|
   puts field_name
   puts field_data.values
   puts field_data.to_s

data/docs/code_samples/default.txt

@@ -2,15 +2,23 @@ require 'uri'
 require 'net/http'
 require 'net/https'
 
-url = URI('https://api.mindee.net/v1/products/mindee/my-endpoint/my-version/predict')
+api_key = "my-api-key"
+account = "my-account"
+endpoint = "my-endpoint"
+version = "my-version"
+
+url = URI("https://api.mindee.net/v1/products/#{account}/#{endpoint}/v#{version}/predict")
 file = '/path/to/the/file.ext'
 
 http = Net::HTTP.new(url.host, url.port)
 http.use_ssl = true
 
 request = Net::HTTP::Post.new(url)
-request['Authorization'] = 'Token my-api-key'
+request['Authorization'] = "Token #{api_key}"
 request.set_form([['document', File.open(file)]], 'multipart/form-data')
 
 response = http.request(request)
+if !response.kind_of? Net::HTTPSuccess
+  raise response.msg
+end
 puts response.read_body

data/docs/code_samples/expense_receipts_v4.txt

@@ -3,12 +3,17 @@ require 'mindee'
 # Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::ReceiptV4)
+# 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::Receipt::ReceiptV4
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 
 # Print the document-level parsed data
-# puts result.inference.prediction
+# puts result.document.inference.prediction

data/docs/code_samples/expense_receipts_v5.txt

@@ -1,14 +1,19 @@
 require 'mindee'
 
-# Init a new client, specifying an API key
+# Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::ReceiptV5)
+# 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::Receipt::ReceiptV5
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 
 # Print the document-level parsed data
-# puts result.inference.prediction
+# puts result.document.inference.prediction

data/docs/code_samples/financial_document_v1.txt

@@ -3,12 +3,17 @@ require 'mindee'
 # Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::FinancialDocumentV1)
+# 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::FinancialDocument::FinancialDocumentV1
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 
 # Print the document-level parsed data
-# puts result.inference.prediction
+# puts result.document.inference.prediction

data/docs/code_samples/idcard_fr_v1.txt

@@ -3,12 +3,17 @@ require 'mindee'
 # Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::FR::IdCardV1)
+# 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::IdCard::IdCardV1
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 
 # Print the document-level parsed data
-# puts result.inference.prediction
+# puts result.document.inference.prediction

data/docs/code_samples/invoice_splitter_v1_async.txt

@@ -0,0 +1,66 @@
+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')
+
+# Put the document class in a local variable to keep the code DRY
+doc_class = Mindee::Product::InvoiceSplitter::InvoiceSplitterV1
+
+# Limit the amount of API calls to retrieve your document
+MAX_RETRIES = 10
+
+# How many seconds to wait in-between tries
+INTERVAL_SECS = 6
+
+# Counter to keep track of how many times we try to retrieve the document
+times_tried = 1
+
+queue_result = mindee_client.enqueue(
+  input_source,
+  doc_class
+)
+
+# Get the id of the queue (job)
+queue_id = queue_result.job.id
+
+# Recursive function that tries to retrieve the completed document.
+# If the document is not "complete", try again
+def get_doc_from_async_queue(
+    queue_id,
+    mindee_client,
+    doc_class,
+    times_tried=0,
+    interval_secs=INTERVAL_SECS,
+    max_retries=MAX_RETRIES
+  )
+    # Have we exceeded our retry count?
+    if times_tried >= max_retries
+      raise "Maximum retries reached #{times_tried}"
+    end
+
+    # Wait for a few seconds before fetching
+    sleep interval_secs
+
+    # Fetch and parse the result, using the same type
+    parsed_result = mindee_client.parse_queued(queue_id, doc_class)
+
+    # Check whether the result is ready
+    if parsed_result.job.status == Mindee::Parsing::Common::JobStatus::COMPLETED
+        # Print a brief summary of the parsed data
+        puts parsed_result.document
+        return
+    # Otherwise, try again...
+    else
+      get_doc_from_async_queue(
+        queue_id, mindee_client,
+        doc_class,
+        times_tried+1
+      )
+    end
+end
+
+# Start the recursion...
+get_doc_from_async_queue(queue_id, mindee_client, doc_class)

data/docs/code_samples/invoices_v4.txt

@@ -3,12 +3,17 @@ require 'mindee'
 # Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::InvoiceV4)
+# 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::Invoice::InvoiceV4
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 
 # Print the document-level parsed data
-# puts result.inference.prediction
+# puts result.document.inference.prediction

data/docs/code_samples/license_plates_v1.txt

@@ -3,12 +3,17 @@ require 'mindee'
 # Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::EU::LicensePlateV1)
+# 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::EU::LicensePlate::LicensePlateV1
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 
 # Print the document-level parsed data
-# puts result.inference.prediction
+# puts result.document.inference.prediction

data/docs/code_samples/passport_v1.txt

@@ -3,12 +3,17 @@ require 'mindee'
 # Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/the/file.ext')
-  .parse(Mindee::Prediction::PassportV1)
+# 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::Passport::PassportV1
+)
 
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 
 # Print the document-level parsed data
-# puts result.inference.prediction
+# puts result.document.inference.prediction