mindee 2.2.0 → 3.0.0

data/docs/code_samples/proof_of_address_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::ProofOfAddressV1)
+# 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::ProofOfAddress::ProofOfAddressV1
+)
 
 # 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/ruby-api-builder.md

@@ -9,52 +9,51 @@ created with the [API Builder](https://developers.mindee.com/docs/overview).
 > 📘 **Info**
 >
 > We used a data model that will be different from yours.
-> To modify this to your own custom API, change the `add_endpoint` call with your own parameters.
+> To modify this to your own custom API, change the `mindee_client.create_endpoint` 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').add_endpoint(
-  'john',
-  'wnine',
-  version: '1.1' # optional, if not set, use the latest version of the model
-)
-
-# Load a file from disk and parse it
-result = mindee_client.doc_from_path('/path/to/file.ext')
-  .parse(Mindee::Prediction::CustomV1, endpoint_name: 'wnine')
+mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Print a summary of the document prediction in RST format
-puts result
+# Create an endpoint for your custom product
+custom_endpoint = mindee_client.create_endpoint(
+  account_name: 'john',
+  endpoint_name: 'wnine',
+  version: '1.1' # optional, if not set, uses the latest version of the model
+)
 ```
 
-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.
+> **Note:** 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.
+If your document is not an OTS API, the document's endpoint must be specified when calling the `parse` method.
 
 ```ruby
-result = mindee_client.doc_from_path('/path/to/custom_file')
-  .parse(Mindee::Prediction::CustomV1, endpoint_name: 'wnine')
-puts result
+mindee_client.parse(
+  input_source,
+  Mindee::Product::Custom::CustomV1,
+  endpoint: custom_endpoint
+)
+
+
+# Print a summary of the document prediction in RST format
+puts result.document
 ```
 
 > 📘 **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:
+> If your custom document has the same name as one of the [off-the-shelf APIs](https://developers.mindee.com/docs/what-is-off-the-shelf-api) document,
+> you **must** specify your account name when creating the `create_endpoint` method:
 
 ```ruby
-mindee_client = Mindee::Client.new.add_endpoint(
-  'receipt',
-  'john'
+custom_endpoint = mindee_client.create_endpoint(
+  endpoint_name: 'receipt',
+  account_name: 'john'
 )
-
-result = mindee_client.doc_from_path('/path/to/receipt.jpg')
-  .parse(Mindee::Prediction::CustomV1, account_name: 'john')
 ```
 
 ## Document Fields
@@ -81,21 +80,21 @@ Individual field values can be accessed by using the field's API name, in the ex
 
 ```ruby
 # raw data, list of each word object
-pp result.inference.prediction.fields[:address].values
+pp result.document.inference.prediction.fields[:address].values
 
 # list of all values
-puts result.inference.prediction.fields[:address].contents_list
+puts result.document.inference.prediction.fields[:address].contents_list
 
 # default string representation
-puts result.inference.prediction.fields[:address].to_s
+puts result.document.inference.prediction.fields[:address].to_s
 
 # custom string representation
-puts result.inference.prediction.fields[:address].contents_str(separator: '_')
+puts result.document.inference.prediction.fields[:address].contents_str(separator: '_')
 ```
 
 To iterate over all the fields:
 ```ruby
-result.inference.prediction.fields.each do |name, info|
+result.document.inference.prediction.fields.each do |name, info|
   puts name
   puts info.values
 end

data/docs/ruby-getting-started.md

@@ -72,7 +72,7 @@ Using Mindee's APIs can be broken down into the following steps:
 Let's take a deep dive into how this works.
 
 ## Initializing the Client
-The `Client` centralizes document configurations in a single object.
+The `Client` automatically connects to the default endpoints for each product (or creates one with given parameters for Custom APIs).
 
 The `Client` requires your [API key](https://developers.mindee.com/docs/make-your-first-request#create-an-api-key).
 
@@ -121,15 +121,25 @@ There are a few different ways of loading a document file, depending on your use
 * [File Object](#file-object)
 * [Base64](#base64)
 * [Bytes](#bytes)
+* [Urls](#url)
 
 ### Path
 Load from a file directly from disk. Requires an absolute path, as a string.
 
 ```ruby
-result = mindee_client.doc_from_path("/path/to/the/invoice.jpg").parse(Mindee::Prediction::InvoiceV4)
+# 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::Invoice::InvoiceV4
+)
 # Print a full summary of the parsed data in RST format
-puts result
+puts result.document
 ```
 
 ### File Object
@@ -138,13 +148,14 @@ A normal Ruby file object with a path. Must be in binary mode.
 **Note**: The original filename is required when calling the method.
 
 ```ruby
-result = nil
 File.open(INVOICE_FILE, 'rb') do |fo|
-  result = mindee_client.doc_from_file(fo, "invoice.jpg").parse(Mindee::Prediction::InvoiceV4)
+  input_source = mindee_client.source_from_file(fo, "invoice.jpg")
 end
 
-# Print a full summary of the parsed data in RST format
-puts result
+result = mindee_client.parse(
+  input_source,
+  Mindee::Product::Invoice::InvoiceV4
+)
 ```
 
 ### Base64
@@ -154,10 +165,13 @@ Load file contents from a base64-encoded string.
 
 ```ruby
 b64_string = "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLD...."
-result = mindee_client.doc_from_b64string(b64_string, "receipt.jpg").parse(Mindee::Prediction::ReceiptV4)
 
-# Print a full summary of the parsed data in RST format
-puts result
+input_source = mindee_client.source_from_b64string(b64_string, "receipt.jpg")
+
+result = mindee_client.parse(
+  input_source,
+  Mindee::Product::Receipt::ReceiptV5
+)
 ```
 
 ### Bytes
@@ -167,33 +181,60 @@ Requires raw bytes.
 
 ```ruby
 raw_bytes = b"%PDF-1.3\n%\xbf\xf7\xa2\xfe\n1 0 ob..."
-result = mindee_client.doc_from_bytes(raw_bytes, "invoice.pdf").parse(Mindee::Prediction::InvoiceV4)
+input_source = mindee_client.source_from_bytes(raw_bytes, "invoice.pdf")
 
-# Print a full summary of the parsed data in RST format
-puts result
+result = mindee_client.parse(
+  input_source,
+  Mindee::Product::Invoice::InvoiceV4
+)
 ```
 
+### URL
+Requires an url as a String.
+
+**Note**: the url must start with `https://`.
+```ruby
+input_source = mindee_client.source_from_url("https://www.example.com/invoice.pdf")
+
+result = mindee_client.parse(
+  input_source,
+  Mindee::Product::Invoice::InvoiceV4
+)
+```
+
+
 ## Sending a File
 To send a file to the API, we need to specify how to process the document.
 This will determine which API endpoint is used and how the API return will be handled internally by the library.
 
-More specifically, we need to set a `Mindee::Prediction` class as the first parameter of the `parse` method.
+More specifically, we need to set a `Mindee::Product` class as the first parameter of the `create_endpoint` method.
 
-This is because the `parse` method's' return type depends on its first argument.
+This is because the `Endpoint`'s urls will be set according to it
 
-Each document type available in the library has its corresponding class, which inherit from the base `Mindee::Prediction` class.
+Each document type available in the library has its corresponding class, which inherit from the base `Mindee::Parsing::Common::Predict` class.
 This is detailed in each document-specific guide.
 
 ### Off-the-Shelf Documents
 Simply setting the correct class is enough:
 ```ruby
-result = doc.parse(Mindee::Prediction::InvoiceV4)
+
+result = mindee_client.parse(
+  input_source,
+  Mindee::Product::Invoice::InvoiceV4
+)
 ```
 
 ### Custom Documents
-The endpoint to use must also be set, this is done in the second argument of the `parse` method:
+For custom documents, the endpoint to use must also be set, and it must take in an `endpoint_name`:
+
 ```ruby
-result = doc.parse(Mindee::Prediction::CustomV1, endpoint_name: 'wnine')
+endpoint = mindee_client.create_endpoint(endpoint_name: 'wnine')
+
+result = mindee_client.parse(
+  input_source,
+  Mindee::Product::Custom::CustomV1,
+  endpoint: endpoint
+)
 ```
 
 This is because the `CustomV1` class is enough to handle the return processing, but the actual endpoint needs to be specified.
@@ -220,10 +261,10 @@ only the highest confidence field data will be shown (this is all done automatic
 
 ```ruby
 # as an object, complete
-pp result.inference.prediction
+pp result.document.inference.prediction
 
 # as a string, summary in RST format
-puts result.inference.prediction
+puts result.document.inference.prediction
 ```
 
 #### Page level prediction
@@ -237,7 +278,7 @@ Single page documents will have a single entry.
 
 Iteration is done like any Ruby array:
 ```ruby
-response.inference.pages.each do |page|
+response.document.inference.pages.each do |page|
     # as an object, complete
     pp page.prediction
 
@@ -256,7 +297,7 @@ If the page requires rotation for correct display, the orientation field gives a
 * 270 degrees: the page must be rotated counterclockwise to be upright
 
 ```ruby
-response.inference.pages.each do |page|
+response.document.inference.pages.each do |page|
   puts page.orientation.value
 end
 ```

data/docs/ruby-invoice-ocr.md

@@ -6,46 +6,55 @@ Using this sample below, we are going to illustrate how to extract the data that
 
 ## Quick Start
 ```ruby
-require 'mindee'
-
-# Init a new client, specifying an API key
+# Init a new client
 mindee_client = Mindee::Client.new(api_key: 'my-api-key')
 
-# Send the file
-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 summary of the document prediction in RST format
-puts result.inference.prediction
+# Print a full summary of the parsed data in RST format
+puts result.document
 ```
 
 Output:
 ```
-:Locale: en; en; CAD;
-:Document type: INVOICE
-:Invoice number: 14
+Invoice V4 Prediction
+=====================
+:Filename:
+:Locale: fr; fr; EUR;
+:Invoice number: 0042004801351
 :Reference numbers: AD29094
-:Invoice date: 2018-09-25
-:Invoice due date: 2018-09-25
+:Invoice date: 2020-02-17
+:Invoice due date: 2020-02-17
 :Supplier name: TURNPIKE DESIGNS CO.
 :Supplier address: 156 University Ave, Toronto ON, Canada M5H 2H7
-:Supplier company registrations:
-:Supplier payment details:
+:Supplier company registrations: 501124705; FR33501124705
+:Supplier payment details: FR7640254025476501124705368;
 :Customer name: JIRO DOI
-:Customer address: 1954 Bloor Street West Toronto, ON, M6P 3K9 Canada
-:Customer company registrations:
-:Taxes: 193.20 8.00%
-:Total net: 2415.00
-:Total taxes: 193.20
-:Total amount: 2608.20
-
+:Customer company registrations: FR00000000000; 111222333
+:Customer address: 1954 Bloon Street West Toronto, ON, M6P 3K9 Canada
 :Line Items:
-====================== ======== ========= ========== ================== ====================================
-Code                   QTY      Price     Amount     Tax (Rate)         Description
-====================== ======== ========= ========== ================== ====================================
-                       1.00     65.00     65.00                         Platinum web hosting package Down...
-                       3.00     2100.00   2100.00                       2 page website design Includes ba...
-                       1.00     250.00    250.00                        Mobile designs Includes responsiv...
-====================== ======== ========= ========== ================== ====================================
+  Code           | QTY    | Price   | Amount   | Tax (Rate)       | Description
+                 |        |         | 4.31     |  (2.10%)         | PQ20 ETIQ ULTRA RESIS METAXXDC
+                 | 1.00   | 65.00   | 75.00    | 10.00            | Platinum web hosting package Dow...
+  XXX81125600010 | 1.00   | 250.01  | 275.51   | 25.50 (10.20%)   | a long string describing the ite...
+  ABC456         | 200.30 | 8.101   | 1622.63  | 121.70 (7.50%)   | Liquid perfection
+                 |        |         |          |                  | CARTOUCHE L NR BROTHER TN247BK
+:Taxes:
+  +---------------+--------+----------+---------------+
+  | Base          | Code   | Rate (%) | Amount        |
+  +===============+========+==========+===============+
+  |               |        | 20.00    | 97.98         |
+  +---------------+--------+----------+---------------+
+:Total tax: 97.98
+:Total net: 489.97
+:Total amount: 587.95
 ```
 
 > 📘 **Info**
@@ -69,34 +78,36 @@ Depending on the field type, there might be additional attributes that will be e
 
 Using the above sample, the following are the basic fields that can be extracted:
 
-- [Orientation](#orientation)
-- [Customer Information](#customer-information)
-- [Dates](#dates)
-- [Locale and Currency](#locale)
-- [Payment Information](#payment-information)
-- [Supplier Information](#supplier-information)
-- [Taxes](#taxes)
-- [Totals](#totals)
-- [Line Items](#line-items)
+- [Quick Start](#quick-start)
+- [Fields](#fields)
+- [Attributes](#attributes)
+  - [Customer Information](#customer-information)
+  - [Dates](#dates)
+  - [Locale](#locale)
+  - [Supplier Information](#supplier-information)
+  - [Taxes](#taxes)
+  - [Totals](#totals)
+  - [Line items](#line-items)
+- [Questions?](#questions)
 
 
 ### Customer Information
 **`customer_name`** (Field): Customer's name
 
 ```ruby
-puts result.inference.prediction.customer_name.value
+puts result.document.inference.prediction.customer_name.value
 ```
 
 **`customer_address`** (Field): Customer's postal address
 
 ```ruby
-puts result.inference.prediction.customer_address.value
+puts result.document.inference.prediction.customer_address.value
 ```
 
 **`customer_company_registrations`** (Array<CompanyRegistration>): Customer's company registration
 
 ```ruby
-result.inference.prediction.customer_company_registrations.each do |registration|
+result.document.inference.prediction.customer_company_registrations.each do |registration|
   puts registration.value
   puts registration.type
 end
@@ -113,13 +124,13 @@ The following date fields are available:
 **`date`**: Date the invoice was issued
 
 ```ruby
-puts result.inference.prediction.date.value
+puts result.document.inference.prediction.date.value
 ```
 
 **`due_date`**: Payment due date of the invoice.
 
 ```ruby
-puts result.inference.prediction.due_date.value
+puts result.document.inference.prediction.due_date.value
 ```
 
 ### Locale
@@ -127,17 +138,17 @@ puts result.inference.prediction.due_date.value
 
 * `locale.language` (String): Language code in [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) format as seen on the document.
 ```ruby
-puts result.inference.prediction.locale.language
+puts result.document.inference.prediction.locale.language
 ```
 
 * `locale.currency` (String): Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format as seen on the document.
 ```ruby
-puts result.inference.prediction.locale.currency
+puts result.document.inference.prediction.locale.currency
 ```
 
 * `locale.country` (String): Country code in [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) alpha-2 format as seen on the document.
 ```ruby
-puts result.inference.prediction.locale.country
+puts result.document.inference.prediction.locale.country
 ```
 
 ### Supplier Information
@@ -145,13 +156,13 @@ puts result.inference.prediction.locale.country
 **`supplier_name`**: Supplier name as written in the invoice (logo or supplier Info).
 
 ```ruby
-puts result.inference.prediction.supplier_name.value
+puts result.document.inference.prediction.supplier_name.value
 ```
 
 **`supplier_address`**: Supplier address as written in the invoice.
 
 ```ruby
-puts result.inference.prediction.supplier_address.value
+puts result.document.inference.prediction.supplier_address.value
 ```
 
 **`supplier__payment_details`** (Array< PaymentDetails >): List of invoice's supplier payment details.
@@ -160,25 +171,25 @@ Each object in the list contains extra attributes:
 * `iban` (String)
 ```ruby
 # Show the IBAN of the first payment
-puts result.inference.prediction.supplier_payment_details[0].iban
+puts result.document.inference.prediction.supplier_payment_details[0].iban
 ```
 
 * `swift` (String)
 ```ruby
 # Show the SWIFT of the first payment
-puts result.inference.prediction.supplier_payment_details[0].swift
+puts result.document.inference.prediction.supplier_payment_details[0].swift
 ```
 
 * `routing_number` (String)
 ```ruby
 # Show the routing number of the first payment
-puts result.inference.prediction.supplier_payment_details[0].routing_number
+puts result.document.inference.prediction.supplier_payment_details[0].routing_number
 ```
 
 * `account_number` (String)
 ```ruby
 # Show the account number of the first payment
-puts result.inference.prediction.supplier_payment_details[0].account_number
+puts result.document.inference.prediction.supplier_payment_details[0].account_number
 ```
 
 **`supplier_company_registrations`** (Array< CompanyRegistration >):
@@ -187,7 +198,7 @@ Each object in the list contains an extra attribute:
 
 * `type` (String): Type of company registration number among predefined categories.
 ```ruby
-result.inference.prediction.supplier_company_registrations.each do |registration|
+result.document.inference.prediction.supplier_company_registrations.each do |registration|
   puts registration.value
   puts registration.type
 end
@@ -199,19 +210,19 @@ end
 * `value` (Float): The tax amount.
 ```ruby
 # Show the amount of the first tax
-puts result.inference.prediction.taxes[0].value
+puts result.document.inference.prediction.taxes[0].value
 ```
 
 * `code` (String): The tax code (HST, GST... for Canadian; City Tax, State tax for US, etc..).
 ```ruby
 # Show the code of the first tax
-puts result.inference.prediction.taxes[0].code
+puts result.document.inference.prediction.taxes[0].code
 ```
 
 * `rate` (Float): The tax rate.
 ```ruby
 # Show the rate of the first tax
-puts result.inference.prediction.taxes[0].rate
+puts result.document.inference.prediction.taxes[0].rate
 ```
 
 ### Totals
@@ -219,19 +230,19 @@ puts result.inference.prediction.taxes[0].rate
 **`total_amount`** (Field): Total amount including taxes.
 
 ```ruby
-puts result.inference.prediction.total_amount.value
+puts result.document.inference.prediction.total_amount.value
 ```
 
 **`total_net`** (Field): Total amount excluding taxes.
 
 ```ruby
-puts result.inference.prediction.total_net.value
+puts result.document.inference.prediction.total_net.value
 ```
 
 **`total_tax`** (Field): Total tax value from tax lines.
 
 ```ruby
-puts result.inference.prediction.total_tax.value
+puts result.document.inference.prediction.total_tax.value
 ```
 
 ### Line items
@@ -251,7 +262,7 @@ Each object in the list contains:
 * `polygon` (Polygon)
 
 ```ruby
-result.inference.prediction.line_items.each do |line_item|
+result.document.inference.prediction.line_items.each do |line_item|
   pp line_item
 end
 ```