mindee 3.1.1 → 3.3.0

data/docs/financial_document_v1.md

@@ -0,0 +1,384 @@
+---
+title: Financial Document OCR Ruby
+---
+The Ruby OCR SDK supports the [Financial Document API](https://platform.mindee.com/mindee/financial_document).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/financial_document/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Financial Document sample](https://github.com/mindee/client-lib-test-data/blob/main/products/financial_document/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::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: 81c1d637-3a84-41d9-b40a-f72ca2a58826
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/financial_document v1.1
+:Rotation applied: Yes
+
+Prediction
+==========
+:Locale: en; en; USD;
+:Invoice Number:
+:Reference Numbers:
+:Purchase Date: 2014-07-07
+:Due Date: 2014-07-07
+:Total Net: 40.48
+:Total Amount: 53.82
+:Taxes:
+  +---------------+--------+----------+---------------+
+  | Base          | Code   | Rate (%) | Amount        |
+  +===============+========+==========+===============+
+  |               | TAX    |          | 3.34          |
+  +---------------+--------+----------+---------------+
+:Supplier Payment Details:
+:Supplier Name: LOGANS
+:Supplier Company Registrations:
+:Supplier Address: 2513 s stemmons freeway lewisville tx 75067
+:Supplier Phone Number: 9724596042
+:Customer Name:
+:Customer Company Registrations:
+:Customer Address:
+:Document Type: EXPENSE RECEIPT
+:Purchase Subcategory: restaurant
+:Purchase Category: food
+:Total Tax: 3.34
+:Tip and Gratuity: 10.00
+:Purchase Time: 20:20
+:Line Items:
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+  | Description                          | Product code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit Price |
+  +======================================+==============+==========+============+==============+==============+============+
+  | TAX                                  |              |          |            |              | 3.34         |            |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+
+Page Predictions
+================
+
+Page 0
+------
+:Locale: en; en; USD;
+:Invoice Number:
+:Reference Numbers:
+:Purchase Date: 2014-07-07
+:Due Date: 2014-07-07
+:Total Net: 40.48
+:Total Amount: 53.82
+:Taxes:
+  +---------------+--------+----------+---------------+
+  | Base          | Code   | Rate (%) | Amount        |
+  +===============+========+==========+===============+
+  |               | TAX    |          | 3.34          |
+  +---------------+--------+----------+---------------+
+:Supplier Payment Details:
+:Supplier Name: LOGANS
+:Supplier Company Registrations:
+:Supplier Address: 2513 s stemmons freeway lewisville tx 75067
+:Supplier Phone Number: 9724596042
+:Customer Name:
+:Customer Company Registrations:
+:Customer Address:
+:Document Type: EXPENSE RECEIPT
+:Purchase Subcategory: restaurant
+:Purchase Category: food
+:Total Tax: 3.34
+:Tip and Gratuity: 10.00
+:Purchase Time: 20:20
+:Line Items:
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+  | Description                          | Product code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit Price |
+  +======================================+==============+==========+============+==============+==============+============+
+  | TAX                                  |              |          |            |              | 3.34         |            |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+```
+
+# 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.
+
+
+### Amount Field
+The amount field `AmountField` only has one constraint: its **value** is a `Float` (or `nil`).
+
+
+### Classification Field
+The classification field `ClassificationField` does not implement all the basic `Field` attributes. It only implements **value**, **confidence** and **page_id**.
+
+> Note: a classification field's `value is always a `String`.
+
+
+### Company Registration Field
+Aside from the basic `Field` attributes, the company registration field `CompanyRegistrationField` also implements the following:
+
+* **type** (`String`): the type of company.
+
+### 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.
+
+### Locale Field
+The locale field `LocaleField` only implements the **value**, **confidence** and **page_id** base `Field` attributes, but it comes with its own:
+
+* **language** (`String`): ISO 639-1 language code (e.g.: `en` for English). Can be `nil`.
+* **country** (`String`): ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code for countries (e.g.: `GRB` or `GB` for "Great Britain"). Can be `nil`.
+* **currency** (`String`): ISO 4217 code for currencies (e.g.: `USD` for "US Dollars"). Can be `nil`.
+
+### Payment Details Field
+Aside from the basic `Field` attributes, the payment details field `PaymentDetailsField` also implements the following:
+
+* **account_number** (`String`): number of an account, expressed as a string. Can be `nil`.
+* **iban** (`String`): International Bank Account Number. Can be `nil`.
+* **routing_number** (`String`): routing number of an account. Can be `nil`.
+* **swift** (`String`): the account holder's bank's SWIFT Business Identifier Code (BIC). Can be `nil`.
+
+### String Field
+The text field `StringField` only has one constraint: it's **value** is a `String` (or `nil`).
+
+### Taxes Field
+#### Tax
+Aside from the basic `Field` attributes, the tax field `TaxField` also implements the following:
+
+* **rate** (`Float`): the tax rate applied to an item can be expressed as a percentage. Can be `nil`.
+* **code** (`String`): tax code (or equivalent, depending on the origin of the document). Can be `nil`.
+* **base** (`Float`): base amount used for the tax. Can be `nil`.
+
+> Note: currently `TaxField` is not used on its own, and is accessed through a parent `Taxes` object, an array-like structure.
+
+#### Taxes (Array)
+The `Taxes` field represents an array-like collection of `TaxField` objects. As it is the representation of several objects, it has access to a custom `to_s` method that can render a `TaxField` object as a table line.
+
+## Specific Fields
+Fields which are specific to this product; they are not used in any other product.
+
+### Line Items Field
+List of line item details.
+
+A `FinancialDocumentV1LineItem` implements the following attributes:
+
+* `description` (String): The item description.
+* `product_code` (String): The product code referring to the item.
+* `quantity` (Float): The item quantity
+* `tax_amount` (Float): The item tax amount.
+* `tax_rate` (Float): The item tax rate in percentage.
+* `total_amount` (Float): The item total amount.
+* `unit_price` (Float): The item unit price.
+
+# Attributes
+The following fields are extracted for Financial Document V1:
+
+## Purchase Category
+**category** ([ClassificationField](#classification-field)): The purchase category among predefined classes.
+
+```rb
+puts result.document.inference.prediction.category.value
+```
+
+## Customer Address
+**customer_address** ([StringField](#string-field)): The address of the customer.
+
+```rb
+puts result.document.inference.prediction.customer_address.value
+```
+
+## Customer Company Registrations
+**customer_company_registrations** (Array<[CompanyRegistrationField](#company-registration-field)>): List of company registrations associated to the customer.
+
+```rb
+for customer_company_registrations_elem in result.document.inference.prediction.customer_company_registrations do
+  puts customer_company_registrations_elem.value
+end
+```
+
+## Customer Name
+**customer_name** ([StringField](#string-field)): The name of the customer.
+
+```rb
+puts result.document.inference.prediction.customer_name.value
+```
+
+## Purchase Date
+**date** ([DateField](#date-field)): The date the purchase was made.
+
+```rb
+puts result.document.inference.prediction.date.value
+```
+
+## Document Type
+**document_type** ([ClassificationField](#classification-field)): One of: 'INVOICE', 'CREDIT NOTE', 'CREDIT CARD RECEIPT', 'EXPENSE RECEIPT'.
+
+```rb
+puts result.document.inference.prediction.document_type.value
+```
+
+## Due Date
+**due_date** ([DateField](#date-field)): The date on which the payment is due.
+
+```rb
+puts result.document.inference.prediction.due_date.value
+```
+
+## Invoice Number
+**invoice_number** ([StringField](#string-field)): The invoice number or identifier.
+
+```rb
+puts result.document.inference.prediction.invoice_number.value
+```
+
+## Line Items
+**line_items** (Array<[FinancialDocumentV1LineItem](#line-items-field)>): List of line item details.
+
+```rb
+for line_items_elem in result.document.inference.prediction.line_items do
+  puts line_items_elem.value
+end
+```
+
+## Locale
+**locale** ([LocaleField](#locale-field)): The locale detected on the document.
+
+```rb
+puts result.document.inference.prediction.locale.value
+```
+
+## Reference Numbers
+**reference_numbers** (Array<[StringField](#string-field)>): List of Reference numbers, including PO number.
+
+```rb
+for reference_numbers_elem in result.document.inference.prediction.reference_numbers do
+  puts reference_numbers_elem.value
+end
+```
+
+## Purchase Subcategory
+**subcategory** ([ClassificationField](#classification-field)): The purchase subcategory among predefined classes for transport and food.
+
+```rb
+puts result.document.inference.prediction.subcategory.value
+```
+
+## Supplier Address
+**supplier_address** ([StringField](#string-field)): The address of the supplier or merchant.
+
+```rb
+puts result.document.inference.prediction.supplier_address.value
+```
+
+## Supplier Company Registrations
+**supplier_company_registrations** (Array<[CompanyRegistrationField](#company-registration-field)>): List of company registrations associated to the supplier.
+
+```rb
+for supplier_company_registrations_elem in result.document.inference.prediction.supplier_company_registrations do
+  puts supplier_company_registrations_elem.value
+end
+```
+
+## Supplier Name
+**supplier_name** ([StringField](#string-field)): The name of the supplier or merchant.
+
+```rb
+puts result.document.inference.prediction.supplier_name.value
+```
+
+## Supplier Payment Details
+**supplier_payment_details** (Array<[PaymentDetailsField](#payment-details-field)>): List of payment details associated to the supplier.
+
+```rb
+for supplier_payment_details_elem in result.document.inference.prediction.supplier_payment_details do
+  puts supplier_payment_details_elem.value
+end
+```
+
+## Supplier Phone Number
+**supplier_phone_number** ([StringField](#string-field)): The phone number of the supplier or merchant.
+
+```rb
+puts result.document.inference.prediction.supplier_phone_number.value
+```
+
+## Taxes
+**taxes** (Array<[TaxField](#taxes-field)>): List of tax lines information.
+
+```rb
+for taxes_elem in result.document.inference.prediction.taxes do
+  puts taxes_elem.to_s
+end
+```
+
+## Purchase Time
+**time** ([StringField](#string-field)): The time the purchase was made.
+
+```rb
+puts result.document.inference.prediction.time.value
+```
+
+## Tip and Gratuity
+**tip** ([AmountField](#amount-field)): The total amount of tip and gratuity
+
+```rb
+puts result.document.inference.prediction.tip.value
+```
+
+## Total Amount
+**total_amount** ([AmountField](#amount-field)): The total amount paid: includes taxes, tips, fees, and other charges.
+
+```rb
+puts result.document.inference.prediction.total_amount.value
+```
+
+## Total Net
+**total_net** ([AmountField](#amount-field)): The net amount paid: does not include taxes, fees, and discounts.
+
+```rb
+puts result.document.inference.prediction.total_net.value
+```
+
+## Total Tax
+**total_tax** ([AmountField](#amount-field)): The total amount of taxes.
+
+```rb
+puts result.document.inference.prediction.total_tax.value
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/{ruby-getting-started.md → getting_started.md}

@@ -1,8 +1,7 @@
-This guide will help you get started with the Mindee Ruby  OCR SDK to easily extract data from your documents.
-
-The Ruby client supports [Invoice](https://developers.mindee.com/docs/ruby-invoice-ocr), [receipt](https://developers.mindee.com/docs/ruby-receipt-ocr),  [passport](https://developers.mindee.com/docs/ruby-passport-ocr),  OCR APIs and [custom-built API](https://developers.mindee.com/docs/ruby-api-builder) from the API Builder.
-
-You can view the source code on [GitHub](https://github.com/mindee/mindee-api-ruby).
+---
+title: Ruby Getting Started
+---
+This guide will help you get the most out of the Mindee Ruby client library to easily extract data from your documents.
 
 ## Installation
 
@@ -62,6 +61,7 @@ gem install mindee@<version>
 ```
 
 ## Usage
+
 Using Mindee's APIs can be broken down into the following steps:
 
 1. [Initialize a Client](#initializing-the-client)
@@ -202,7 +202,6 @@ result = mindee_client.parse(
 )
 ```
 
-
 ## 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.
@@ -302,5 +301,22 @@ response.document.inference.pages.each do |page|
 end
 ```
 
+## 🧪 Experimental Features
+
+### PDF repair
+
+Some PDF files might appear fine on your computer, but can be rejected by the server.
+This _experimental_ feature attempts to fix the file's header information before sending it to the server.
+
+> ⚠️ **Warning**: This feature copies your file and then **alters** it. The original file will be left alone, but the copy might get partially corrupted, and improperly parsed as a result. Use at your own discretion.
+
+To enable it, simply set the `fix_pdf` flag to `true` during source creation:
+
+```rb
+input_source = mindee_client.source_from_file(input_file, "name-of-my-file.ext", fix_pdf: true)
+```
+
+Note: This only works for local files, files sent by URL will not be processed.
+
 ## Questions?
 [Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/idcard_fr_v2.md

@@ -0,0 +1,253 @@
+---
+title: FR Carte Nationale d'Identité OCR Ruby
+---
+The Ruby OCR SDK supports the [Carte Nationale d'Identité API](https://platform.mindee.com/mindee/idcard_fr).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/idcard_fr/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Carte Nationale d'Identité sample](https://github.com/mindee/client-lib-test-data/blob/main/products/idcard_fr/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::IdCard::IdCardV2
+)
+
+# 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: d33828f1-ef7e-4984-b9df-a2bfaa38a78d
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/idcard_fr v2.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Nationality:
+:Card Access Number: 175775H55790
+:Document Number:
+:Given Name(s): Victor
+                Marie
+:Surname: DAMBARD
+:Alternate Name:
+:Date of Birth: 1994-04-24
+:Place of Birth: LYON 4E ARRONDISSEM
+:Gender: M
+:Expiry Date: 2030-04-02
+:Mrz Line 1: IDFRADAMBARD<<<<<<<<<<<<<<<<<<075025
+:Mrz Line 2: 170775H557903VICTOR<<MARIE<9404246M5
+:Mrz Line 3:
+:Date of Issue: 2015-04-03
+:Issuing Authority: SOUS-PREFECTURE DE BELLE (02)
+
+Page Predictions
+================
+
+Page 0
+------
+:Document Type: OLD
+:Document Sides: RECTO & VERSO
+:Nationality:
+:Card Access Number: 175775H55790
+:Document Number:
+:Given Name(s): Victor
+                Marie
+:Surname: DAMBARD
+:Alternate Name:
+:Date of Birth: 1994-04-24
+:Place of Birth: LYON 4E ARRONDISSEM
+:Gender: M
+:Expiry Date: 2030-04-02
+:Mrz Line 1: IDFRADAMBARD<<<<<<<<<<<<<<<<<<075025
+:Mrz Line 2: 170775H557903VICTOR<<MARIE<9404246M5
+:Mrz Line 3:
+:Date of Issue: 2015-04-03
+:Issuing Authority: SOUS-PREFECTURE DE BELLE (02)
+```
+
+# 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.
+
+
+### Classification Field
+The classification field `ClassificationField` does not implement all the basic `Field` attributes. It only implements **value**, **confidence** and **page_id**.
+
+> Note: a classification field's `value is always 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`).
+
+## Page-Level Fields
+Some fields are constrained to the page level, and so will not be retrievable to through the document.
+
+# Attributes
+The following fields are extracted for Carte Nationale d'Identité V2:
+
+## Alternate Name
+**alternate_name** ([StringField](#string-field)): The alternate name of the card holder.
+
+```rb
+puts result.document.inference.prediction.alternate_name.value
+```
+
+## Issuing Authority
+**authority** ([StringField](#string-field)): The name of the issuing authority.
+
+```rb
+puts result.document.inference.prediction.authority.value
+```
+
+## Date of Birth
+**birth_date** ([DateField](#date-field)): The date of birth of the card holder.
+
+```rb
+puts result.document.inference.prediction.birth_date.value
+```
+
+## Place of Birth
+**birth_place** ([StringField](#string-field)): The place of birth of the card holder.
+
+```rb
+puts result.document.inference.prediction.birth_place.value
+```
+
+## Card Access Number
+**card_access_number** ([StringField](#string-field)): The card access number (CAN).
+
+```rb
+puts result.document.inference.prediction.card_access_number.value
+```
+
+## Document Number
+**document_number** ([StringField](#string-field)): The document number.
+
+```rb
+puts result.document.inference.prediction.document_number.value
+```
+
+## Document Sides
+[📄](#page-level-fields "This field is only present on individual pages.")**document_side** ([ClassificationField](#classification-field)): The sides of the document which are visible.
+
+```rb
+for document_side_elem in result.document.document_side do
+  puts document_side_elem.value
+end
+```
+
+## Document Type
+[📄](#page-level-fields "This field is only present on individual pages.")**document_type** ([ClassificationField](#classification-field)): The document type or format.
+
+```rb
+for document_type_elem in result.document.document_type do
+  puts document_type_elem.value
+end
+```
+
+## Expiry Date
+**expiry_date** ([DateField](#date-field)): The expiry date of the identification card.
+
+```rb
+puts result.document.inference.prediction.expiry_date.value
+```
+
+## Gender
+**gender** ([StringField](#string-field)): The gender of the card holder.
+
+```rb
+puts result.document.inference.prediction.gender.value
+```
+
+## Given Name(s)
+**given_names** (Array<[StringField](#string-field)>): The given name(s) of the card holder.
+
+```rb
+for given_names_elem in result.document.inference.prediction.given_names do
+  puts given_names_elem.value
+end
+```
+
+## Date of Issue
+**issue_date** ([DateField](#date-field)): The date of issue of the identification card.
+
+```rb
+puts result.document.inference.prediction.issue_date.value
+```
+
+## Mrz Line 1
+**mrz1** ([StringField](#string-field)): The Machine Readable Zone, first line.
+
+```rb
+puts result.document.inference.prediction.mrz1.value
+```
+
+## Mrz Line 2
+**mrz2** ([StringField](#string-field)): The Machine Readable Zone, second line.
+
+```rb
+puts result.document.inference.prediction.mrz2.value
+```
+
+## Mrz Line 3
+**mrz3** ([StringField](#string-field)): The Machine Readable Zone, third line.
+
+```rb
+puts result.document.inference.prediction.mrz3.value
+```
+
+## Nationality
+**nationality** ([StringField](#string-field)): The nationality of the card holder.
+
+```rb
+puts result.document.inference.prediction.nationality.value
+```
+
+## Surname
+**surname** ([StringField](#string-field)): The surname of the card holder.
+
+```rb
+puts result.document.inference.prediction.surname.value
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)