mindee 3.1.1 → 3.3.0

data/docs/code_samples/invoice_splitter_v1_async.txt

@@ -6,61 +6,13 @@ 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(
+result = mindee_client.enqueue_and_parse(
   input_source,
-  doc_class
+  Mindee::Product::InvoiceSplitter::InvoiceSplitterV1
 )
 
-# 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
+# Print a full summary of the parsed data in RST format
+puts result.document
 
-# Start the recursion...
-get_doc_from_async_queue(queue_id, mindee_client, doc_class)
+# Print the document-level parsed data
+# puts result.document.inference.prediction

data/docs/code_samples/multi_receipts_detector_v1.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::MultiReceiptsDetector::MultiReceiptsDetectorV1
+)
+
+# 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/us_w9_v1.txt

@@ -0,0 +1,16 @@
+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::US::W9::W9V1
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document

data/docs/cropper_v1.md

@@ -0,0 +1,97 @@
+---
+title: Cropper OCR Ruby
+---
+The Ruby OCR SDK supports the [Cropper API](https://platform.mindee.com/mindee/cropper).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/cropper/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Cropper sample](https://github.com/mindee/client-lib-test-data/blob/main/products/cropper/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::Cropper::CropperV1
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document
+```
+
+**Output (RST):**
+```rst
+########
+Document
+########
+:Mindee ID: 149ce775-8302-4798-8649-7eda9fb84a1a
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/cropper v1.0
+:Rotation applied: No
+
+Prediction
+==========
+
+Page Predictions
+================
+
+Page 0
+------
+:Document Cropper: Polygon with 26 points.
+                   Polygon with 25 points.
+```
+
+# 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.
+
+
+### Position Field
+The position field `PositionField` does not implement all the basic `Field` attributes, only **bounding_box**, **polygon** and **page_id**. On top of these, it has access to:
+
+* **rectangle** (`Mindee::Geometry::Quadrilateral`): a Polygon with four points that may be oriented (even beyond canvas).
+* **quadrangle** (`Mindee::Geometry::Quadrilateral`): a free polygon made up of four points.
+
+## 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 Cropper V1:
+
+## Document Cropper
+[📄](#page-level-fields "This field is only present on individual pages.")**cropping** (Array<[PositionField](#position-field)>): List of documents found in the image.
+
+```rb
+for page in result.document.inference.pages do
+  for cropping_elem in page.prediction.cropping do
+    puts cropping_elem.polygon
+  end
+end
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/custom_v1.md

@@ -0,0 +1,109 @@
+---
+title: Custom API Ruby
+---
+The Ruby OCR SDK supports [custom-built APIs](https://developers.mindee.com/docs/build-your-first-document-parsing-api).
+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://platform.mindee.com/api-builder).
+
+# 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')
+
+# Initialize a custom endpoint for this product
+custom_endpoint = mindee_client.create_endpoint(
+  account_name: 'my-account',
+  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.document
+
+# Print the document-level parsed data
+# puts result.document.inference.prediction
+
+# Looping over all prediction values
+result.document.inference.prediction.fields.each do |field_name, field_data|
+  puts field_name
+  puts field_data.values
+  puts field_data.to_s
+end
+```
+
+# Custom Endpoints
+
+You may have noticed in the previous step that in order to access a custom build, you will need to provide an account and an endpoint name at the very least.
+
+Although it is optional, the version number should match the latest version of your build in most use-cases.
+If it is not set, it will default to "1".
+
+
+# Field Types
+
+## Custom Fields
+
+### List Field
+
+A `ListField` is a special type of custom list that implements the following:
+
+* **confidence** (`Float`): the confidence score of the field prediction.
+* **reconstructed** (`Boolean`): indicates whether or not an object was reconstructed (not extracted as the API gave it).
+* **values** (`Array<`[ListFieldItem](#list-field-item)`>`): list of value fields
+
+Since the inner contents can vary, the value isn't accessed through a property, but rather through the following functions:
+* **contents_list()** (`[Array, Hash, String, nil]`): returns a list of values for each element.
+* **contents_str(separator:' ')** (`String`): returns a list of concatenated values, with an optional **separator** `String` between them.
+* **to_s()**: returns a string representation of all values, with an empty space between each of them.
+
+#### List Field Item
+
+Values of `ListField`s are stored in a `ListFieldItem` structure, which is implemented as follows:
+* **content** (`String`): extracted content of the prediction
+* **confidence** (`Float`): the confidence score of the prediction
+* **bounding_box** (`Quadrilateral`): 4 relative vertices corrdinates of a rectangle containing the word in the document.
+* **polygon** (`Polygon`): vertices of a polygon containing the word.
+* **page_id** (`Integer`): the ID of the page, is `nil` when at document-level.
+
+### Classification Field
+
+A `ClassificationField` is a special type of custom classification that implements the following:
+
+* **value** (`String`): the value of the classification. Corresponds to one of the values specified during training.
+* **confidence** (`Float`): the confidence score of the field prediction.
+* **to_s()**: returns a string representation of all values, with an empty space between each of them.
+
+# Attributes
+
+Custom builds always have access to at least two attributes:
+
+## Fields
+
+**fields** ({`String`=> [ListField](#list-field)}): 
+
+```rb
+puts result.document.inference.prediction.fields[:my_field].value
+```
+
+## Classifications
+
+**classifications** ({`String` => [ClassificationField](#classification-field)}): The purchase category among predefined classes.
+
+```js
+console.log(result.document.inference.prediction.classifications["my-classification"].to_s);
+```
+
+# Questions?
+
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/expense_receipts_v5.md

@@ -0,0 +1,306 @@
+---
+title: Receipt OCR Ruby
+---
+The Ruby OCR SDK supports the [Receipt API](https://platform.mindee.com/mindee/expense_receipts).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/expense_receipts/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Receipt sample](https://github.com/mindee/client-lib-test-data/blob/main/products/expense_receipts/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::Receipt::ReceiptV5
+)
+
+# 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: ce41e37a-65d8-4de1-b34b-1c92ab04b1ae
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/expense_receipts v5.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Expense Locale: en-GB; en; GB; GBP;
+:Purchase Category: food
+:Purchase Subcategory: restaurant
+:Document Type: EXPENSE RECEIPT
+:Purchase Date: 2016-02-26
+:Purchase Time: 15:20
+:Total Amount: 10.20
+:Total Net: 8.50
+:Total Tax: 1.70
+:Tip and Gratuity:
+:Taxes:
+  +---------------+--------+----------+---------------+
+  | Base          | Code   | Rate (%) | Amount        |
+  +===============+========+==========+===============+
+  | 8.50          | VAT    | 20.00    | 1.70          |
+  +---------------+--------+----------+---------------+
+:Supplier Name: CLACHAN
+:Supplier Company Registrations: 232153895
+                                 232153895
+:Supplier Address: 34 kingley street w1b 5qh
+:Supplier Phone Number: 02074940834
+:Line Items:
+  +--------------------------------------+----------+--------------+------------+
+  | Description                          | Quantity | Total Amount | Unit Price |
+  +======================================+==========+==============+============+
+  | Meantime Pale                        | 2.00     | 10.20        |            |
+  +--------------------------------------+----------+--------------+------------+
+
+Page Predictions
+================
+
+Page 0
+------
+:Expense Locale: en-GB; en; GB; GBP;
+:Purchase Category: food
+:Purchase Subcategory: restaurant
+:Document Type: EXPENSE RECEIPT
+:Purchase Date: 2016-02-26
+:Purchase Time: 15:20
+:Total Amount: 10.20
+:Total Net: 8.50
+:Total Tax: 1.70
+:Tip and Gratuity:
+:Taxes:
+  +---------------+--------+----------+---------------+
+  | Base          | Code   | Rate (%) | Amount        |
+  +===============+========+==========+===============+
+  | 8.50          | VAT    | 20.00    | 1.70          |
+  +---------------+--------+----------+---------------+
+:Supplier Name: CLACHAN
+:Supplier Company Registrations: 232153895
+                                 232153895
+:Supplier Address: 34 kingley street w1b 5qh
+:Supplier Phone Number: 02074940834
+:Line Items:
+  +--------------------------------------+----------+--------------+------------+
+  | Description                          | Quantity | Total Amount | Unit Price |
+  +======================================+==========+==============+============+
+  | Meantime Pale                        | 2.00     | 10.20        |            |
+  +--------------------------------------+----------+--------------+------------+
+```
+
+# 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`.
+
+### 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 `ReceiptV5LineItem` implements the following attributes:
+
+* `description` (String): The item description.
+* `quantity` (Float): The item quantity.
+* `total_amount` (Float): The item total amount.
+* `unit_price` (Float): The item unit price.
+
+# Attributes
+The following fields are extracted for Receipt V5:
+
+## Purchase Category
+**category** ([ClassificationField](#classification-field)): The purchase category among predefined classes.
+
+```rb
+puts result.document.inference.prediction.category.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: 'CREDIT CARD RECEIPT', 'EXPENSE RECEIPT'.
+
+```rb
+puts result.document.inference.prediction.document_type.value
+```
+
+## Line Items
+**line_items** (Array<[ReceiptV5LineItem](#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
+```
+
+## Expense Locale
+**locale** ([LocaleField](#locale-field)): The locale detected on the document.
+
+```rb
+puts result.document.inference.prediction.locale.value
+```
+
+## 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 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, discounts, fees, tips, and gratuity.
+
+```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)