mindee 4.7.1 → 4.8.0

data/docs/advanced_file_operations.md

@@ -1,109 +0,0 @@
----
-title: Advanced File Operations
-category: 622b805aaec68102ea7fcbc2
-slug: ruby-advanced-file-operations
-parentDoc: 6294d97ee723f1008d2ab28e
----
-
-> ❗️ Disclaimer: the file operations listed below do not directly manipulate the files you will pass to the library,
-> They will instead create a copy before applying any operations, which means that the file you send may not be an exact copy of the file the server will receive.
-> To avoid any unexpected or unwanted result, you can save a copy of the created file locally to inspect it visually before sending it.
-
-## Image compression
-
-The compression functionality for image files (JPEG, PNG, etc.) via the `compress!` method available on a
-LocalInputSource. This method allows you to reduce file size by specifying quality and dimension constraints.
-
-Example:
-
-```rb
-# Compress an image with custom parameters.
-input_source.compress!(quality: 85, max_width: 1024, max_height: 768)
-```
-> ⚠️ Warning: Compression alters the original image data.
-> We strongly advise you inspect a compressed file before sending it:
-> ```rb
-> # Compress using a quality of 50%:
-> input_source.compress!(quality: 50)
-> input_source.write_to_file('path/to/my/compressed/file_50.jpg')
-> ```
-
-For reference, here's what the following levels of compression on this image will look like:
-
-**Original:**
-![Invoice sample](https://github.com/mindee/client-lib-test-data/blob/main/products/invoices/default_sample.jpg?raw=true)
-
-**85% compressed:**
-![85% sample](https://github.com/mindee/client-lib-test-data/blob/main/file_operations/compression/compressed_ruby_85.jpg?raw=true)
-
-**50% compressed:**
-![50% sample](https://github.com/mindee/client-lib-test-data/blob/main/file_operations/compression/compressed_ruby_50.jpg?raw=true)
-
-**10% compressed:**
-![10% sample](https://github.com/mindee/client-lib-test-data/blob/main/file_operations/compression/compressed_ruby_10.jpg?raw=true)
-
-
-## PDF operations
-
-PDF operations include both compression and fixing features.
-These are specifically designed to handle challenges associated with PDF files, such as large file sizes and formatting
-issues.
-
-### PDF compression
-
-> 🧪 PDF compression is an **experimental** feature that rasterizes each page of the PDF (similar to how images are
-> compressed) to reduce its overall size.
-> 
-> Because the process involves re-rendering the PDF’s contents, some source text may be lost or rendered differently.
-> Use this feature with caution.
-
-
-```rb
-# Load a local input source.
-input_file_path = "path/to/your/file.pdf"
-output_file_path = "path/to/the/compressed/file.pdf"
-pdf_input = Mindee::Input::Source::PathInputSource.new(input_file_path)
-
-# We advise you test the quality value yourself, as results may vary greatly depending on the input file
-pdf_input.compress!(quality: 50)
-
-# Write the output file locally for visual checking:
-File.write(output_file_path, pdf_input.io_stream.read)
-```
-
-> 🚧 Be warned that the source text (the text embedded in the PDF itself) might not render properly,
-> and so source PDFs will be ignored by default.
-> 
-> You can bypass this using:
-
-```rb
-pdf_input.compress!(quality: 50, force_source_text: true)
-```
-
-Or alternatively, you can try to approximate the re-rendering of the source-text using:
-
-```rb
-pdf_input.compress!(quality: 50, force_source_text: true, disable_source_text: false)
-```
-
-### PDF Repair
-
-The PDF repair feature attempts to rescue PDFs with invalid or broken header information.
-This can sometimes help when files get rejected by the server.
-
-Example:
-```rb
-# Load a PDF file with the repair_pdf flag enabled.
-input_source = mindee_client.source_from_file(file, "document.pdf", repair_pdf: true)
-```
-
-> ⚠️ Warning: PDF fixing alters the input file by re-writing header information.
-> Use this feature only when required, as it might affect the integrity of the document file.
-
----
-
-Feel free to expand these examples and adjust the parameters as needed for your projects. For further details on
-authentication and usage, you can refer to the [Getting Started Guide](getting_started.md).
-
-# Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/code_samples/us_mail_v2_async.txt

@@ -1,24 +0,0 @@
-#
-# 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::US::UsMail::UsMailV2
-)
-
-# 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/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)