mindee 4.7.2 → 4.8.0

data/docs/getting_started.md

@@ -1,257 +0,0 @@
----
-title: Getting Started
-category: 622b805aaec68102ea7fcbc2
-slug: ruby-getting-started
-parentDoc: 6294d97ee723f1008d2ab28e
----
-> 📘 This guide will help you get the most out of the Mindee Ruby client library to easily extract data from your documents.
-
-## Installation
-
-### Requirements
-The following Ruby versions are tested and supported: 3.0, 3.1, 3.2, 3.3
-
-### Standard Installation
-To quickly get started with the Ruby Client Library, 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` automatically connects to the default endpoints for each product (or creates one with given parameters for
-Universal APIs).
-
-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
-```rb
-# 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:
-```rb
-# 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, you can use a:
-
-* [File path](https://developers.mindee.com/docs/ruby-document-loading#loading-from-a-local-path): using the Mindee Client's `source_from_path()` method.
-* [File Object](https://developers.mindee.com/docs/ruby-document-loading#loading-from-a-file-object): using the Mindee Client's `source_from_file()` method.
-* [Base64 String](https://developers.mindee.com/docs/ruby-document-loading#loading-from-a-base64-encoded-string): using the Mindee Client's `source_from_b64string()` method.
-* [Raw Byte sequence](https://developers.mindee.com/docs/ruby-document-loading#loading-from-raw-bytes): using the Mindee Client's `source_from_bytes()` method.
-* [URL](https://developers.mindee.com/docs/ruby-document-loading#loading-by-url): using the Mindee Client's `source_from_url()` method.
-
-More details about file loading on the [dedicated page](https://developers.mindee.com/docs/ruby-document-loading).
-
-## 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::Product` class as the first parameter of the `create_endpoint` method.
-
-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::Parsing::Common::Predict` class.
-
-This is detailed in each document-specific guide.
-
-### Off-the-Shelf Documents
-Simply setting the correct class is enough:
-
-```rb
-
-result = mindee_client.parse(
-  input_source,
-  Mindee::Product::Invoice::InvoiceV4
-)
-```
-
-#### Specific call method
-Some products, such as InvoiceV4, ReceiptV5 & FinancialDocumentV1 support both asynchronous polling and synchronous
-HTTP calls.
-We recommend letting the client library decide which is better by default, but you can override the behavior by setting
-the `enqueue` parameter to `true` or `false`.
-
-```rb
-
-result = mindee_client.parse(
-  input_source,
-  Mindee::Product::Invoice::InvoiceV4,
-  enqueue: false
-)
-```
-
-> 🚧 WARNING: this feature is not available for all products, and may result in errors if used inappropriately.
-> Only use it if you are certain of what you are doing.
-### Universal Documents (docTI)
-For custom documents, the endpoint to use must also be set, and it must take in an `endpoint_name`:
-
-```rb
-endpoint = mindee_client.create_endpoint(endpoint_name: 'wnine', account_name: 'my-account')
-
-result = mindee_client.parse(
-  input_source,
-  Mindee::Product::Universal::Universal,
-  endpoint: endpoint
-)
-```
-
-This is because the `Universal` 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 (using the Universal product). 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).
-
-```rb
-# as an object, complete
-pp result.document.inference.prediction
-
-# as a string, summary in RST format
-puts result.document.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:
-```rb
-response.document.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
-
-```rb
-response.document.inference.pages.each do |page|
-  puts page.orientation.value
-end
-```
-
-
-## Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/global_products/barcode_reader_v1.md

@@ -1,125 +0,0 @@
----
-title: Barcode Reader
-category: 622b805aaec68102ea7fcbc2
-slug: ruby-barcode-reader-ocr
-parentDoc: 67b49df15b843f3fa9cd622b
----
-The Ruby Client Library supports the [Barcode Reader API](https://platform.mindee.com/mindee/barcode_reader).
-
-
-> 📝 Product Specs
->
-> | Specification                  | Details                                            |
-> | ------------------------------ | -------------------------------------------------- |
-> | Endpoint Name                  | `barcode_reader`                                   |
-> | Recommended Version            | `v1.0`                                             |
-> | Supports Polling/Webhooks      | ❌ No                                              |
-> | Support Synchronous HTTP Calls | ✔️ Yes                                             |
-> | Geography                      | 🌐 Global                                          |
-
-
-Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/barcode_reader/default_sample.jpg),
-we are going to illustrate how to extract the data that we want using the Ruby Client Library.
-![Barcode Reader sample](https://github.com/mindee/client-lib-test-data/blob/main/products/barcode_reader/default_sample.jpg?raw=true)
-
-# Quick-Start
-```rb
-#
-# Install the Ruby client library by running:
-# gem install mindee
-#
-
-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::BarcodeReader::BarcodeReaderV1
-)
-
-# 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: f9c48da1-a306-4805-8da8-f7231fda2d88
-:Filename: default_sample.jpg
-
-Inference
-#########
-:Product: mindee/barcode_reader v1.0
-:Rotation applied: Yes
-
-Prediction
-==========
-:Barcodes 1D: Mindee
-:Barcodes 2D: https://developers.mindee.com/docs/barcode-reader-ocr
-              I love paperwork! - Said no one ever
-
-Page Predictions
-================
-
-Page 0
-------
-:Barcodes 1D: Mindee
-:Barcodes 2D: https://developers.mindee.com/docs/barcode-reader-ocr
-              I love paperwork! - Said no one ever
-```
-
-# 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`, `bool`): 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, always `nil` when at document-level.
-* **reconstructed** (`bool`): indicates whether 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.
-
-### String Field
-The text field `StringField` only has one constraint: it's **value** is a `String` (or `nil`).
-
-# Attributes
-The following fields are extracted for Barcode Reader V1:
-
-## Barcodes 1D
-**codes_1d** (Array<[StringField](#string-field)>): List of decoded 1D barcodes.
-
-```rb
-result.document.inference.prediction.codes_1d do |codes_1d_elem|
-  puts codes_1d_elem.value
-end
-```
-
-## Barcodes 2D
-**codes_2d** (Array<[StringField](#string-field)>): List of decoded 2D barcodes.
-
-```rb
-result.document.inference.prediction.codes_2d do |codes_2d_elem|
-  puts codes_2d_elem.value
-end
-```
-
-# Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/global_products/bill_of_lading_v1.md

@@ -1,276 +0,0 @@
----
-title: Bill of Lading
-category: 622b805aaec68102ea7fcbc2
-slug: ruby-bill-of-lading-ocr
-parentDoc: 67b49df15b843f3fa9cd622b
----
-The Ruby Client Library supports the [Bill of Lading API](https://platform.mindee.com/mindee/bill_of_lading).
-
-
-> 📝 Product Specs
->
-> | Specification                  | Details                                            |
-> | ------------------------------ | -------------------------------------------------- |
-> | Endpoint Name                  | `bill_of_lading`                                   |
-> | Recommended Version            | `v1.1`                                             |
-> | Supports Polling/Webhooks      | ✔️ Yes                                             |
-> | Support Synchronous HTTP Calls | ❌ No                                              |
-> | Geography                      | 🌐 Global                                          |
-
-> 🔐 Polling Limitations
->
-> | Setting                         | Parameter name          | Default Value |
-> | ------------------------------- | ----------------------- | ------------- |
-> | Initial Delay Before Polling    | `initial_delay_seconds` | 2 seconds     |
-> | Default Delay Between Calls     | `delay_sec`             | 1.5 seconds   |
-> | Polling Attempts Before Timeout | `max_retries`           | 80 retries    |
-
-
-Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/bill_of_lading/default_sample.jpg),
-we are going to illustrate how to extract the data that we want using the Ruby Client Library.
-![Bill of Lading sample](https://github.com/mindee/client-lib-test-data/blob/main/products/bill_of_lading/default_sample.jpg?raw=true)
-
-# Quick-Start
-```rb
-#
-# Install the Ruby client library by running:
-# gem install mindee
-#
-
-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::BillOfLading::BillOfLadingV1
-)
-
-# 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: 3b5250a1-b52c-4e0b-bc3e-2f0146b04e29
-:Filename: default_sample.jpg
-
-Inference
-#########
-:Product: mindee/bill_of_lading v1.1
-:Rotation applied: No
-
-Prediction
-==========
-:Bill of Lading Number: XYZ123456
-:Shipper:
-  :Address: 123 OCEAN DRIVE, SHANGHAI, CHINA
-  :Email:
-  :Name: GLOBAL FREIGHT SOLUTIONS INC.
-  :Phone: 86-21-12345678
-:Consignee:
-  :Address: 789 TRADE STREET, SINGAPORE 567890, SINGAPORE
-  :Email:
-  :Name: PACIFIC TRADING CO.
-  :Phone: 65-65432100
-:Notify Party:
-  :Address: 789 TRADE STREET, SINGAPORE 567890, SINGAPORE
-  :Email:
-  :Name: PACIFIC TRADING CO.
-  :Phone: 65-65432100
-:Carrier:
-  :Name: GLOBAL SHIPPING CO.,LTD.
-  :Professional Number:
-  :SCAC:
-:Items:
-  +--------------------------------------+--------------+-------------+------------------+----------+-------------+
-  | Description                          | Gross Weight | Measurement | Measurement Unit | Quantity | Weight Unit |
-  +======================================+==============+=============+==================+==========+=============+
-  | ELECTRONIC COMPONENTS\nP/N: 12345... | 500.00       | 1.50        | cbm              | 1.00     | kgs         |
-  +--------------------------------------+--------------+-------------+------------------+----------+-------------+
-:Port of Loading: SHANGHAI, CHINA
-:Port of Discharge: LOS ANGELES, USA
-:Place of Delivery: LOS ANGELES, USA
-:Date of issue: 2022-09-30
-:Departure Date:
-```
-
-# 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`, `bool`): 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, always `nil` when at document-level.
-* **reconstructed** (`bool`): indicates whether 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.
-
-### 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`).
-
-## Specific Fields
-Fields which are specific to this product; they are not used in any other product.
-
-### Shipper Field
-The party responsible for shipping the goods.
-
-A `BillOfLadingV1Shipper` implements the following attributes:
-
-* `address` (String): The address of the shipper.
-* `email` (String): The  email of the shipper.
-* `name` (String): The name of the shipper.
-* `phone` (String): The phone number of the shipper.
-Fields which are specific to this product; they are not used in any other product.
-
-### Consignee Field
-The party to whom the goods are being shipped.
-
-A `BillOfLadingV1Consignee` implements the following attributes:
-
-* `address` (String): The address of the consignee.
-* `email` (String): The  email of the shipper.
-* `name` (String): The name of the consignee.
-* `phone` (String): The phone number of the consignee.
-Fields which are specific to this product; they are not used in any other product.
-
-### Notify Party Field
-The party to be notified of the arrival of the goods.
-
-A `BillOfLadingV1NotifyParty` implements the following attributes:
-
-* `address` (String): The address of the notify party.
-* `email` (String): The  email of the shipper.
-* `name` (String): The name of the notify party.
-* `phone` (String): The phone number of the notify party.
-Fields which are specific to this product; they are not used in any other product.
-
-### Carrier Field
-The shipping company responsible for transporting the goods.
-
-A `BillOfLadingV1Carrier` implements the following attributes:
-
-* `name` (String): The name of the carrier.
-* `professional_number` (String): The professional number of the carrier.
-* `scac` (String): The Standard Carrier Alpha Code (SCAC) of the carrier.
-Fields which are specific to this product; they are not used in any other product.
-
-### Items Field
-The goods being shipped.
-
-A `BillOfLadingV1CarrierItem` implements the following attributes:
-
-* `description` (String): A description of the item.
-* `gross_weight` (Float): The gross weight of the item.
-* `measurement` (Float): The measurement of the item.
-* `measurement_unit` (String): The unit of measurement for the measurement.
-* `quantity` (Float): The quantity of the item being shipped.
-* `weight_unit` (String): The unit of measurement for weights.
-
-# Attributes
-The following fields are extracted for Bill of Lading V1:
-
-## Bill of Lading Number
-**bill_of_lading_number** ([StringField](#string-field)): A unique identifier assigned to a Bill of Lading document.
-
-```rb
-puts result.document.inference.prediction.bill_of_lading_number.value
-```
-
-## Carrier
-**carrier** ([BillOfLadingV1Carrier](#carrier-field)): The shipping company responsible for transporting the goods.
-
-```rb
-puts result.document.inference.prediction.carrier.value
-```
-
-## Items
-**carrier_items** (Array<[BillOfLadingV1CarrierItem](#items-field)>): The goods being shipped.
-
-```rb
-result.document.inference.prediction.carrier_items do |carrier_items_elem|
-  puts carrier_items_elem.value
-end
-```
-
-## Consignee
-**consignee** ([BillOfLadingV1Consignee](#consignee-field)): The party to whom the goods are being shipped.
-
-```rb
-puts result.document.inference.prediction.consignee.value
-```
-
-## Date of issue
-**date_of_issue** ([DateField](#date-field)): The date when the bill of lading is issued.
-
-```rb
-puts result.document.inference.prediction.date_of_issue.value
-```
-
-## Departure Date
-**departure_date** ([DateField](#date-field)): The date when the vessel departs from the port of loading.
-
-```rb
-puts result.document.inference.prediction.departure_date.value
-```
-
-## Notify Party
-**notify_party** ([BillOfLadingV1NotifyParty](#notify-party-field)): The party to be notified of the arrival of the goods.
-
-```rb
-puts result.document.inference.prediction.notify_party.value
-```
-
-## Place of Delivery
-**place_of_delivery** ([StringField](#string-field)): The place where the goods are to be delivered.
-
-```rb
-puts result.document.inference.prediction.place_of_delivery.value
-```
-
-## Port of Discharge
-**port_of_discharge** ([StringField](#string-field)): The port where the goods are unloaded from the vessel.
-
-```rb
-puts result.document.inference.prediction.port_of_discharge.value
-```
-
-## Port of Loading
-**port_of_loading** ([StringField](#string-field)): The port where the goods are loaded onto the vessel.
-
-```rb
-puts result.document.inference.prediction.port_of_loading.value
-```
-
-## Shipper
-**shipper** ([BillOfLadingV1Shipper](#shipper-field)): The party responsible for shipping the goods.
-
-```rb
-puts result.document.inference.prediction.shipper.value
-```
-
-# Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)