mindee-lite 5.0.0.beta1

data/docs/code_samples/invoices_v4_async.txt

@@ -0,0 +1,24 @@
+#
+# Install the Ruby client library by running:
+# gem install mindee
+#
+
+require 'mindee'
+
+# Init a new client
+mindee_client = Mindee::V1::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::V1::Product::Invoice::InvoiceV4
+)
+
+# 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/multi_receipts_detector_v1.txt

@@ -0,0 +1,24 @@
+#
+# Install the Ruby client library by running:
+# gem install mindee
+#
+
+require 'mindee'
+
+# Init a new client
+mindee_client = Mindee::V1::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::V1::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/passport_v1.txt

@@ -0,0 +1,24 @@
+#
+# Install the Ruby client library by running:
+# gem install mindee
+#
+
+require 'mindee'
+
+# Init a new client
+mindee_client = Mindee::V1::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::V1::Product::Passport::PassportV1
+)
+
+# 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/resume_v1_async.txt

@@ -0,0 +1,24 @@
+#
+# Install the Ruby client library by running:
+# gem install mindee
+#
+
+require 'mindee'
+
+# Init a new client
+mindee_client = Mindee::V1::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::V1::Product::Resume::ResumeV1
+)
+
+# 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/v2_classification.txt

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'mindee'
+require 'mindee/v2/product'
+
+input_path = '/path/to/the/file.ext'
+api_key = 'MY_API_KEY'
+model_id = 'MY_MODEL_ID'
+
+# Init a new client
+mindee_client = Mindee::V2::Client.new(api_key: api_key)
+
+# Set inference parameters
+classification_params = {
+    # ID of the model, required.
+    model_id: model_id,
+}
+
+# Load a file from disk
+input_source = Mindee::Input::Source::PathInputSource.new(input_path)
+
+# Send for processing
+response = mindee_client.enqueue_and_get_result(
+    Mindee::V2::Product::Classification::Classification,
+    input_source,
+    classification_params
+)
+
+# Access the classification result
+puts response.inference.result.classification

data/docs/code_samples/v2_crop.txt

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'mindee'
+require 'mindee/v2/product'
+
+input_path = '/path/to/the/file.ext'
+api_key = 'MY_API_KEY'
+model_id = 'MY_MODEL_ID'
+
+# Init a new client
+mindee_client = Mindee::V2::Client.new(api_key: api_key)
+
+# Set inference parameters
+crop_params = {
+    # ID of the model, required.
+    model_id: model_id,
+}
+
+# Load a file from disk
+input_source = Mindee::Input::Source::PathInputSource.new(input_path)
+
+# Send for processing
+response = mindee_client.enqueue_and_get_result(
+    Mindee::V2::Product::Crop::Crop,
+    input_source,
+    crop_params
+)
+
+# Access the result crops
+puts response.inference.result.crops

data/docs/code_samples/v2_extraction.txt

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'mindee'
+require 'mindee/v2/product'
+
+input_path = '/path/to/the/file.ext'
+api_key = 'MY_API_KEY'
+model_id = 'MY_MODEL_ID'
+
+# Init a new client
+mindee_client = Mindee::V2::Client.new(api_key: api_key)
+
+# Set inference parameters
+extraction_params = {
+    # ID of the model, required.
+    model_id: model_id,
+
+    # Options: set to `true` or `false` to override defaults
+
+    # Enhance extraction accuracy with Retrieval-Augmented Generation.
+    rag: nil,
+    # Extract the full text content from the document as strings.
+    raw_text: nil,
+    # Calculate bounding box polygons for all fields.
+    polygon: nil,
+    # Boost the precision and accuracy of all extractions.
+    # Calculate confidence scores for all fields.
+    confidence: nil
+}
+
+# Load a file from disk
+input_source = Mindee::Input::Source::PathInputSource.new(input_path)
+
+# Send for processing
+response = mindee_client.enqueue_and_get_result(
+    Mindee::V2::Product::Extraction::Extraction,
+    input_source,
+    extraction_params
+)
+
+# Print a brief summary of the parsed data
+puts response.inference

data/docs/code_samples/v2_extraction_webhook.txt

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'mindee'
+require 'mindee/v2/product'
+
+input_path = '/path/to/the/file.ext'
+api_key = 'MY_API_KEY'
+model_id = 'MY_MODEL_ID'
+
+# Init a new client
+mindee_client = Mindee::V2::Client.new(api_key: api_key)
+
+extraction_params = {
+    # ID of the model, required.
+    model_id: model_id,
+    # Add any number of webhook IDs here.
+    webhook_ids: ['MY_WEBHOOK_ID'],
+
+    # Options: set to `true` or `false` to override defaults
+
+    # Enhance extraction accuracy with Retrieval-Augmented Generation.
+    rag: nil,
+    # Extract the full text content from the document as strings.
+    raw_text: nil,
+    # Calculate bounding box polygons for all fields.
+    polygon: nil,
+    # Boost the precision and accuracy of all extractions.
+    # Calculate confidence scores for all fields.
+    confidence: nil
+}
+
+# Load a file from disk
+input_source = Mindee::Input::Source::PathInputSource.new(input_path)
+
+# Send for processing
+response = mindee_client.enqueue(
+    Mindee::V2::Product::Extraction::Extraction,
+    input_source,
+    extraction_params
+)
+
+# Print the job ID
+job_id = response.job.id
+
+puts job_id

data/docs/code_samples/v2_ocr.txt

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'mindee'
+require 'mindee/v2/product'
+
+input_path = '/path/to/the/file.ext'
+api_key = 'MY_API_KEY'
+model_id = 'MY_MODEL_ID'
+
+# Init a new client
+mindee_client = Mindee::V2::Client.new(api_key: api_key)
+
+# Set inference parameters
+ocr_params = {
+    # ID of the model, required.
+    model_id: model_id,
+}
+
+# Load a file from disk
+input_source = Mindee::Input::Source::PathInputSource.new(input_path)
+
+# Send for processing
+response = mindee_client.enqueue_and_get_result(
+    Mindee::V2::Product::OCR::OCR,
+    input_source,
+    ocr_params
+)
+
+# Access the result OCR pages
+puts response.inference.result.pages

data/docs/code_samples/v2_split.txt

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'mindee'
+require 'mindee/v2/product'
+
+input_path = '/path/to/the/file.ext'
+api_key = 'MY_API_KEY'
+model_id = 'MY_MODEL_ID'
+
+# Init a new client
+mindee_client = Mindee::V2::Client.new(api_key: api_key)
+
+# Set inference parameters
+split_params = {
+    # ID of the model, required.
+    model_id: model_id,
+}
+
+# Load a file from disk
+input_source = Mindee::Input::Source::PathInputSource.new(input_path)
+
+# Send for processing
+response = mindee_client.enqueue_and_get_result(
+    Mindee::V2::Product::Split::Split,
+    input_source,
+    split_params
+)
+
+# Access the result splits
+puts response.inference.result.splits

data/docs/code_samples/workflow_execution.txt

@@ -0,0 +1,28 @@
+#
+# Install the Ruby client library by running:
+# gem install mindee
+#
+
+require 'mindee'
+
+workflow_id = 'workflow-id'
+
+# Init a new client
+mindee_client = Mindee::V1::Client.new
+
+# Load a file from disk
+input_source = mindee_client.source_from_path('path/to/my/file.ext')
+
+# Send the file to the workflow
+result = mindee_client.execute_workflow(
+  input_source,
+  workflow_id,
+# options: { # Optionally, you can provide the following parameters:
+#   document_alias: 'my-document-alias', # Potential alias for the document
+#   priority: Mindee::V1::Parsing::Common::ExecutionPriority::LOW, # Priority of the execution
+#   rag: true # Whether to enable Retrieval-Augmented Generation
+# }
+)
+
+# Print the execution's ID to make sure it worked
+puts result.execution.id

data/docs/code_samples/workflow_polling.txt

@@ -0,0 +1,35 @@
+#
+# Install the Ruby client library by running:
+# gem install mindee
+#
+
+require 'mindee'
+
+workflow_id = 'workflow-id'
+
+# Init a new client
+mindee_client = Mindee::V1::Client.new
+
+# Load a file from disk
+input_source = mindee_client.source_from_path('path/to/my/file.ext')
+
+# Initialize a custom endpoint for this product
+custom_endpoint = mindee_client.create_endpoint(
+  account_name: 'my-account',
+  endpoint_name: 'my-endpoint',
+  version: 'my-version'
+)
+
+# Parse the file
+result = mindee_client.parse(
+  input_source,
+  Mindee::V1::Product::Universal::Universal,
+  endpoint: custom_endpoint,
+  options: {
+    rag: true,
+    workflow_id: workflow_id
+  }
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document

data/examples/auto_invoice_splitter_extraction.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'mindee'
+
+def invoice_splitter_auto_extraction(file_path)
+  mindee_client = Mindee::V1::Client.new(api_key: 'my-api-key')
+  input_source = mindee_client.source_from_path(file_path)
+
+  if input_source.pdf? && input_source.page_count > 1
+    parse_multi_page(mindee_client, input_source)
+  else
+    parse_single_page(mindee_client, input_source)
+  end
+end
+
+def parse_single_page(mindee_client, input_source)
+  invoice_result = mindee_client.parse(
+    input_source,
+    Mindee::V1::Product::Invoice::InvoiceV4
+  )
+  puts invoice_result.document
+end
+
+def parse_multi_page(mindee_client, input_source)
+  pdf_extractor = Mindee::PDF::PDFExtractor.new(input_source)
+  invoice_splitter_response = mindee_client.parse(
+    input_source,
+    Mindee::V1::Product::InvoiceSplitter::InvoiceSplitterV1,
+    options: { close_file: false }
+  )
+  page_groups = invoice_splitter_response.document.inference.prediction.invoice_page_groups
+  extracted_pdfs = pdf_extractor.extract_invoices(page_groups, strict: false)
+
+  extracted_pdfs.each do |extracted_pdf|
+    # Optional: Save the files locally
+    # extracted_pdf.write_to_file("output/path")
+
+    invoice_result = mindee_client.parse(
+      extracted_pdf.as_input_source,
+      Mindee::V1::Product::Invoice::InvoiceV4,
+      options: { close_file: false }
+    )
+    puts invoice_result.document
+  end
+end
+
+my_file_path = '/path/to/the/file.ext'
+invoice_splitter_auto_extraction(my_file_path)

data/examples/auto_multi_receipts_detector_extraction.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'mindee'
+
+mindee_client = Mindee::V1::Client.new(api_key: 'my-api-key')
+def multi_receipts_detection(file_path, mindee_client)
+  input_source = mindee_client.source_from_path(file_path)
+
+  result_multi_receipts = mindee_client.parse(
+    input_source,
+    Mindee::V1::Product::MultiReceiptsDetector::MultiReceiptsDetectorV1,
+    options: { close_file: false }
+  )
+
+  images = Mindee::V1::Extraction.extract_receipts(input_source, result_multi_receipts.document.inference)
+  images.each do |sub_image|
+    # Optional: Save the files locally
+    # sub_image.write_to_file("/path/to/my/extracted/file/folder")
+
+    result_receipt = mindee_client.parse(
+      sub_image.as_source,
+      Mindee::V1::Product::Receipt::ReceiptV5,
+      options: { close_file: false }
+    )
+    puts result_receipt.document
+  end
+end
+
+my_file_path = '/path/to/the/file.ext'
+multi_receipts_detection(my_file_path, mindee_client)

data/lib/mindee/dependency.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Centralized check for optional heavy dependencies
+  module Dependency
+    def self.check_all_dependencies
+      require 'origami'
+      require 'mini_magick'
+      require 'pdf-reader'
+      true
+    rescue LoadError
+      false
+    end
+
+    @all_deps_available = check_all_dependencies
+
+    def self.all_deps_available?
+      check_all_dependencies
+    end
+
+    def self.require_all_deps!
+      raise LoadError, MINDEE_DEPENDENCIES_LOAD_ERROR unless all_deps_available?
+    end
+
+    MINDEE_DEPENDENCIES_LOAD_ERROR = 'Attempted to load Mindee PDF/Image tools without required dependencies. ' \
+                                     "If you need to process local files, please replace the 'mindee-lite' gem " \
+                                     "with the standard 'mindee' gem in your Gemfile."
+  end
+end

data/lib/mindee/error/mindee_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Error
+    # Base class for all custom mindee errors.
+    class MindeeError < StandardError; end
+
+    # Errors relating to library issues.
+    class MindeeAPIError < MindeeError; end
+
+    # Errors relating to misuse of the library.
+    class MindeeConfigurationError < MindeeError; end
+
+    # Errors relating to geometric manipulation issues.
+    class MindeeGeometryError < MindeeError; end
+  end
+end

data/lib/mindee/error/mindee_http_error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'mindee_error'
+
+module Mindee
+  module Error
+    # API HttpError
+    class MindeeHTTPError < MindeeError
+      # @return [String]
+      attr_reader :status_code
+      # @return [Integer]
+      attr_reader :api_code
+      # @return [String]
+      attr_reader :api_details
+      # @return [String]
+      attr_reader :api_message
+
+      # @param http_error [Hash]
+      # @param url [String]
+      # @param code [Integer]
+      def initialize(http_error, url, code)
+        @status_code = code
+        @api_code = http_error['code']
+        @api_details = http_error['details']
+        @api_message = http_error['message']
+        super("#{url} #{@status_code} HTTP error: #{@api_details} - #{@api_message}")
+      end
+    end
+
+    # Base class for all client-side errors.
+    class MindeeHTTPClientError < MindeeHTTPError; end
+
+    # Base class for all server-side errors.
+    class MindeeHTTPServerError < MindeeHTTPError; end
+  end
+end

data/lib/mindee/error/mindee_http_error_v2.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'mindee_error'
+require_relative '../v2/parsing/error_item'
+
+module Mindee
+  module Error
+    # API V2 HttpError
+    class MindeeHTTPErrorV2 < MindeeError
+      # @return [Integer] The HTTP status code returned by the server.
+      attr_reader :status
+      # @return [String] A human-readable explanation specific to the occurrence of the problem.
+      attr_reader :detail
+      # @return [String] A short, human-readable summary of the problem.
+      attr_reader :title
+      # @return [String] A machine-readable code specific to the occurrence of the problem.
+      attr_reader :code
+      # @return [Array<ErrorItem>] A list of explicit error details.
+      attr_reader :errors
+
+      # @param http_error [Hash, Mindee::V2::Parsing::ErrorResponse]
+      def initialize(http_error)
+        if http_error.is_a?(V2::Parsing::ErrorResponse)
+          http_error = { 'detail' => http_error.detail,
+                         'status' => http_error.status,
+                         'title' => http_error.title,
+                         'code' => http_error.code,
+                         'errors' => http_error.errors }
+        end
+        @status = http_error['status']
+        @detail = http_error['detail']
+        @title = http_error['title']
+        @code = http_error['code']
+        @errors = if http_error.key?('errors')
+                    http_error['errors'].map do |error|
+                      Mindee::V2::Parsing::ErrorItem.new(error)
+                    end
+                  else
+                    []
+                  end
+        super("HTTP #{@status} - #{@title} :: #{@code} - #{@detail}")
+      end
+    end
+  end
+end

data/lib/mindee/error/mindee_http_unknown_error_v2.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'mindee_error'
+
+module Mindee
+  module Error
+    # Unknown HTTP error for the V2 API.
+    class MindeeHTTPUnknownErrorV2 < MindeeHTTPErrorV2
+      def initialize(http_error)
+        super({ 'detail' => "Couldn't deserialize server error. Found: #{http_error}",
+                'status' => -1,
+                'title' => 'Unknown Error',
+                'code' => '000-000',
+                'errors' => nil })
+      end
+    end
+  end
+end

data/lib/mindee/error/mindee_input_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Error
+    # Base class for error relating to input documents.
+    class MindeeInputError < MindeeError; end
+
+    # Errors relating to sources (documents) handling.
+    class MindeeSourceError < MindeeInputError; end
+
+    # Errors relating to mime type issues.
+    class MindeeMimeTypeError < MindeeSourceError
+      # @return [String]
+      attr_reader :invalid_mimetype
+
+      # @param mime_type [String]
+      def initialize(mime_type)
+        @invalid_mimetype = mime_type
+        super("'#{@invalid_mimetype}' mime type not allowed, must be one of " \
+              "#{Mindee::Input::Source::ALLOWED_MIME_TYPES.join(', ')}")
+      end
+    end
+
+    # Errors relating to the handling of images.
+    class MindeeImageError < MindeeInputError; end
+
+    # Errors relating to the handling of PDF documents.
+    class MindeePDFError < MindeeInputError; end
+  end
+end

data/lib/mindee/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'error/mindee_error'
+require_relative 'error/mindee_http_error'
+require_relative 'error/mindee_http_error_v2'
+require_relative 'error/mindee_input_error'

data/lib/mindee/geometry/min_max.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Various helper functions & classes for geometry.
+  module Geometry
+    # A set of minimum and maximum values.
+    class MinMax
+      # Minimum
+      # @return [Float]
+      attr_reader :min
+      # Maximum
+      # @return [Float]
+      attr_reader :max
+
+      # @param min [Float]
+      # @param max [Float]
+      def initialize(min, max)
+        @min = min
+        @max = max
+      end
+    end
+  end
+end