mindee 1.2.0 → 2.0.0

data/docs/ruby-getting-started.md

@@ -0,0 +1,265 @@
+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).
+
+## Installation
+
+### Requirements
+The following Ruby versions are tested and supported: 2.6, 2.7, 3.0, 3.1, 3.2
+
+### Standard Installation
+To quickly get started with the Ruby OCR SDK, Install by adding this line to your application's Gemfile:
+
+```shell
+gem 'mindee'
+```
+And then execute:
+
+```shell
+bundle install
+```
+Or you can install it like this:
+
+```shell
+gem install mindee
+```
+Finally, Ruby away!
+
+### Development Installation
+If you'll be modifying the source code, you'll need to install the required libraries to get started.
+
+We recommend using [Bundler](https://bundler.io/).
+
+1. First clone the repo.
+
+```shell
+git clone git@github.com:mindee/mindee-api-ruby.git
+```
+
+2. Navigate to the cloned directory and install all required libraries.
+
+```shell
+cd mindee-api-ruby
+bundle install
+```
+
+## Updating the Library
+It is important to always check the version of the Mindee OCR SDK you are using, as new and updated
+features won’t work on older versions.
+
+To get the latest version of your OCR SDK:
+
+```shell
+gem install mindee
+```
+
+To install a specific version of Mindee:
+
+```shell
+gem install mindee@<version>
+```
+
+## Usage
+Using Mindee's APIs can be broken down into the following steps:
+
+1. [Initialize a `Client`](#initializing-the-client)
+2. [Load a File](#loading-a-document-file)
+3. [Send the File](#sending-a-file) to Mindee's API
+4. [Process the Result](#process-the-result) in some way
+
+Let's take a deep dive into how this works.
+
+## Initializing the Client
+The `Client` centralizes document configurations in a single object.
+
+The `Client` requires your [API key](https://developers.mindee.com/docs/make-your-first-request#create-an-api-key).
+
+You can either pass these directly to the constructor or through environment variables.
+
+
+### Pass the API key directly
+```ruby
+# Init a new client and passing the key directly
+mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+```
+
+### Set the API key in the environment
+API keys should be set as environment variables, especially for any production deployment.
+
+The following environment variable will set the global API key:
+```shell
+MINDEE_API_KEY=my-api-key
+```
+ 
+Then in your code:
+```ruby
+# Init a new client without an API key
+mindee_client = Mindee::Client.new
+```
+
+### Setting the Request Timeout
+The request timeout can be set using an environment variable:
+```shell
+MINDEE_REQUEST_TIMEOUT=200
+```
+
+
+## Loading a Document File
+Before being able to send a document to the API, it must first be loaded.
+
+You don't need to worry about different MIME types, the library will take care of handling
+all supported types automatically.
+
+Once a document is loaded, interacting with it is done in exactly the same way, regardless
+of how it was loaded.
+
+There are a few different ways of loading a document file, depending on your use case:
+
+* [Path](#path)
+* [File Object](#file-object)
+* [Base64](#base64)
+* [Bytes](#bytes)
+
+### 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)
+
+# Print a full summary of the parsed data in RST format
+puts result
+```
+
+### File Object
+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)
+end
+
+# Print a full summary of the parsed data in RST format
+puts result
+```
+
+### Base64
+Load file contents from a base64-encoded string.
+
+**Note**: The original filename is required when calling the method.
+
+```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
+```
+
+### Bytes
+Requires raw bytes.
+
+**Note**: The original filename is required when calling the method.
+
+```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)
+
+# Print a full summary of the parsed data in RST format
+puts result
+```
+
+## 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.
+
+This is because the `parse` method's' return type depends on its first argument.
+
+Each document type available in the library has its corresponding class, which inherit from the base `Mindee::Prediction` 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)
+```
+
+### Custom Documents
+The endpoint to use must also be set, this is done in the second argument of the `parse` method:
+```ruby
+result = doc.parse(Mindee::Prediction::CustomV1, endpoint_name: 'wnine')
+```
+
+This is because the `CustomV1` class is enough to handle the return processing, but the actual endpoint needs to be specified.
+
+## Process the Result
+The response object is common to all documents, including custom documents. The main properties are:
+
+* `id` — Mindee ID of the document
+* `name` — Filename sent to the API
+* `inference` — [Inference](#inference)
+
+### Inference
+Regroups the predictions at the page level, as well as predictions for the entire document.
+
+* `prediction` — [Document level prediction](#document-level-prediction)
+* `pages` — [Page level prediction](#page-level-prediction)
+
+#### Document level prediction
+The `prediction` attribute is a `Prediction` object specific to the type of document being processed.
+It contains the data extracted from the entire document, all pages combined.
+
+It's possible to have the same field in various pages, but at the document level,
+only the highest confidence field data will be shown (this is all done automatically at the API level).
+
+```ruby
+# as an object, complete
+pp result.inference.prediction
+
+# as a string, summary in RST format
+puts result.inference.prediction
+```
+
+#### Page level prediction
+The `pages` attribute is a list of `Prediction` objects.
+
+Each page element contains the data extracted for a particular page of the document.
+The order of the elements in the array matches the order of the pages in the document.
+
+All response objects have this property, regardless of the number of pages.
+Single page documents will have a single entry.
+
+Iteration is done like any Ruby array:
+```ruby
+response.inference.pages.each do |page|
+    # as an object, complete
+    pp page.prediction
+
+    # as a string, summary in RST format
+    puts page.prediction
+end
+```
+
+#### Page Orientation
+The orientation field is only available at the page level as it describes whether the page image should be rotated to be upright.
+
+If the page requires rotation for correct display, the orientation field gives a prediction among these 3 possible outputs:
+
+* 0 degrees: the page is already upright
+* 90 degrees: the page must be rotated clockwise to be upright
+* 270 degrees: the page must be rotated counterclockwise to be upright
+
+```ruby
+response.inference.pages.each do |page|
+  puts page.orientation.value
+end
+```
+
+## Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/ruby-invoice-ocr.md

@@ -0,0 +1,261 @@
+The Ruby OCR SDK supports the [invoice API](https://developers.mindee.com/docs/invoice-ocr) for extracting data from invoices.
+
+Using this sample below, we are going to illustrate how to extract the data that we want using the OCR SDK.
+
+![sample invoice](https://raw.githubusercontent.com/mindee/client-lib-test-data/main/invoice/invoice_1p.jpg)
+
+## Quick Start
+```ruby
+require 'mindee'
+
+# Init a new client, specifying an API key
+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)
+
+# Print a summary of the document prediction in RST format
+puts result.inference.prediction
+```
+
+Output:
+```shell
+:Locale: en; en; CAD;
+:Document type: INVOICE
+:Invoice number: 14
+:Reference numbers: AD29094
+:Invoice date: 2018-09-25
+:Invoice due date: 2018-09-25
+:Supplier name: TURNPIKE DESIGNS CO.
+:Supplier address: 156 University Ave, Toronto ON, Canada M5H 2H7
+:Supplier company registrations:
+:Supplier payment details:
+: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
+
+: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...
+====================== ======== ========= ========== ================== ====================================
+```
+
+**Note:** Line item descriptions are truncated here only for display purposes.
+The full text is available in the [details](#line-items).
+
+## Fields
+Each prediction object contains a set of different fields.
+Each `Field` object contains at a minimum the following attributes:
+
+* `value` (String or Float depending on the field type): corresponds to the field value. Can be `nil` if no value was extracted.
+* `confidence` (Float): the confidence score of the field prediction.
+* `bounding_box` (Array< Array< Float > >): contains exactly 4 relative vertices coordinates (points) of a right rectangle containing the field in the document.
+* `polygon` (Array< Array< Float > >): contains the relative vertices coordinates (points) of a polygon containing the field in the image.
+* `reconstructed` (Boolean): True if the field was reconstructed or computed using other fields.
+
+
+## Attributes
+Depending on the field type, there might be additional attributes that will be extracted in the `Invoice` object.
+
+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)
+
+
+### Customer Information
+**`customer_name`** (Field): Customer's name
+
+```ruby
+puts result.inference.prediction.customer_name.value
+```
+
+**`customer_address`** (Field): Customer's postal address
+
+```ruby
+puts result.inference.prediction.customer_address.value
+```
+
+**`customer_company_registration`** (Array<CompanyRegistration>): Customer's company registration
+
+```ruby
+result.inference.prediction.customer_company_registrations.each do |registration|
+  puts registration
+end
+```
+
+### Dates
+Date fields:
+
+* contain the `date_object` attribute, which is a standard Ruby [date object](https://ruby-doc.org/stdlib-2.7.1/libdoc/date/rdoc/Date.html)
+* have a `value` attribute which is the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) representation of the date.
+
+The following date fields are available:
+
+**`date`**: Date the invoice was issued
+
+```ruby
+puts result.inference.prediction.date.value
+```
+
+**`due_date`**: Payment due date of the invoice.
+
+```ruby
+puts result.inference.prediction.due_date.value
+```
+
+### Locale
+**`locale`** [Locale]: Locale information.
+
+* `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
+```
+
+* `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
+```
+
+* `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
+```
+
+### Supplier Information
+
+**`supplier_name`**: Supplier name as written in the invoice (logo or supplier Info).
+
+```ruby
+puts result.inference.prediction.supplier_name.value
+```
+
+**`supplier_address`**: Supplier address as written in the invoice.
+
+```ruby
+puts result.inference.prediction.supplier_address.value
+```
+
+**`supplier__payment_details`** (Array< PaymentDetails >): List of invoice's supplier payment details.
+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
+```
+
+* `swift` (String)
+```ruby
+# Show the SWIFT of the first payment
+puts result.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
+```
+
+* `account_number` (String)
+```ruby
+# Show the account number of the first payment
+puts result.inference.prediction.supplier_payment_details[0].account_number
+```
+
+**`supplier_company_registrations`** (Array< CompanyRegistration >):
+List of detected supplier's company registration numbers.
+Each object in the list contains an extra attribute:
+
+* `type` (String): Type of company registration number among predefined categories.
+```ruby
+# Show the type of the first registration
+puts result.inference.prediction.supplier_company_registrations[0].type
+```
+
+* `value` (String): Value of the company identifier
+```ruby
+# Show the value of the first registration
+puts result.inference.prediction.supplier_company_registrations[0].value
+```
+
+### Taxes
+**`taxes`** (Array< TaxField >): Contains tax fields as seen on the receipt.
+
+* `value` (Float): The tax amount.
+```ruby
+# Show the amount of the first tax
+puts result.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
+```
+
+* `rate` (Float): The tax rate.
+```ruby
+# Show the rate of the first tax
+puts result.inference.prediction.taxes[0].rate
+```
+
+### Totals
+
+**`total_amount`** (Field): Total amount including taxes.
+
+```ruby
+puts result.inference.prediction.total_amount.value
+```
+
+**`total_net`** (Field): Total amount excluding taxes.
+
+```ruby
+puts result.inference.prediction.total_net.value
+```
+
+**`total_tax`** (Field): Total tax value from tax lines.
+
+```ruby
+puts result.inference.prediction.total_tax.value
+```
+
+### Line items
+
+**`line_items`** (Array<InvoiceLineItem>): Line items details.
+Each object in the list contains:
+
+* `product_code` (String)
+* `description` (String)
+* `quantity` (Float)
+* `unit_price` (Float)
+* `total_amount` (Float)
+* `tax_rate` (Float)
+* `tax_amount` (Float)
+* `confidence` (Float)
+* `page_id` (Integer)
+* `polygon` (Polygon)
+
+```ruby
+result.inference.prediction.line_items.each do |line_item|
+  pp line_item
+end
+```
+
+## Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/ruby-passport-ocr.md

@@ -0,0 +1,156 @@
+The Ruby  OCR SDK supports the [passport API](https://developers.mindee.com/docs/passport-ocr) for extracting data from passports.
+
+Using the sample below, we are going to illustrate how to extract the data that we want using the  OCR SDK.
+
+![sample passport](https://raw.githubusercontent.com/mindee/client-lib-test-data/main/passport/passport.jpeg)
+
+## Quick Start
+```ruby
+require 'mindee'
+
+# Init a new client, specifying an API key
+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::PassportV1)
+
+# Print a summary of the document prediction in RST format
+puts result.inference.prediction
+```
+
+Output:
+```shell
+:Full name: HENERT PUDARSAN
+:Given names: HENERT
+:Surname: PUDARSAN
+:Country: GBR
+:ID Number: 707797979
+:Issuance date: 2012-04-22
+:Birth date: 1995-05-20
+:Expiry date: 2017-04-22
+:MRZ 1: P<GBRPUDARSAN<<HENERT<<<<<<<<<<<<<<<<<<<<<<<
+:MRZ 2: 7077979792GBR9505209M1704224<<<<<<<<<<<<<<00
+:MRZ: P<GBRPUDARSAN<<HENERT<<<<<<<<<<<<<<<<<<<<<<<7077979792GBR9505209M1704224<<<<<<<<<<<<<<00
+```
+
+## Fields
+Each prediction object contains a set of different fields.
+Each `Field` object contains at a minimum the following attributes:
+
+* `value` (String or Float depending on the field type): corresponds to the field value. Can be `nil` if no value was extracted.
+* `confidence` (Float): the confidence score of the field prediction.
+* `bounding_box` (Array< Array< Float > >): contains exactly 4 relative vertices coordinates (points) of a right rectangle containing the field in the document.
+* `polygon` (Array< Array< Float > >): contains the relative vertices coordinates (points) of a polygon containing the field in the image.
+* `reconstructed` (Boolean): True if the field was reconstructed or computed using other fields.
+
+
+## Attributes
+Depending on the field type specified, additional attributes can be extracted from the `Passport` object.
+
+Using the above sample, the following are the basic fields that can be extracted:
+
+- [Orientation](#orientation)
+- [Birth Place](#birth-place)
+- [Country](#country)
+- [Dates (Expiry, Issuance, Birth)](#dates)
+- [Gender](#gender)
+- [Given Names](#given-names)
+- [ID Number](#id)
+- [Machine Readable Zone](#machine-readable-zone)
+- [Surname](#surname)
+
+### Birth Place
+
+**`birth_place`** (Field): Passport owner birthplace.
+
+```ruby
+puts result.inference.prediction.birth_place.value
+```
+
+### Country
+**`country`** (Field): Passport country in [ISO 3166-1 alpha-3 code format](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) (3-letter code).
+
+```ruby
+puts result.inference.prediction.country.value
+```
+
+### Dates
+Date fields:
+
+* contain the `date_object` attribute, which is a standard Ruby [date object](https://ruby-doc.org/stdlib-2.7.1/libdoc/date/rdoc/Date.html)
+* have a `value` attribute which is the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) representation of the date.
+
+The following date fields are available:
+
+**`expiry_date`**: Passport expiry date.
+
+```ruby
+puts result.inference.prediction.expiry_date.value
+```
+
+**`issuance_date`**: Passport date of issuance.
+
+```ruby
+puts result.inference.prediction.issuance_date.value
+```
+
+**`birth_date`**: Passport's owner date of birth.
+
+```ruby
+puts result.inference.prediction.birth_date.value
+```
+
+### Gender
+
+**`gender`** (Field): Passport owner's gender (M / F).
+
+```ruby
+puts result.inference.prediction.gender.value
+```
+
+### Names
+
+**`given_names`** (Array< Field >): List of passport owner's given names.
+
+```ruby
+result.inference.prediction.given_names.each do |name|
+  puts name
+end
+```
+
+**`surname`** (Field): Passport's owner surname.
+
+```ruby
+puts result.inference.prediction.surname.value
+```
+
+### ID
+
+**`id_number`** (Field): Passport identification number.
+
+```ruby
+puts result.inference.prediction.id_number.value
+```
+
+### Machine-Readable Zone
+
+**`mrz1`** (Field): Passport first line of machine-readable zone.
+
+```ruby
+puts result.inference.prediction.mrz1.value
+```
+
+**`mrz2`** (Field): Passport second line of machine-readable zone.
+
+```ruby
+puts result.inference.prediction.mrz2.value
+```
+
+**`mrz`** (Field): Reconstructed passport full machine-readable zone from mrz1 and mrz2.
+
+```ruby
+puts result.inference.prediction.mrz.value
+```
+
+## Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)