mindee 4.12.0 → 5.0.0.beta1

data/docs/code_samples/multi_receipts_detector_v1.txt

@@ -6,7 +6,7 @@
 require 'mindee'
 
 # Init a new client
-mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+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')
@@ -14,7 +14,7 @@ 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
+  Mindee::V1::Product::MultiReceiptsDetector::MultiReceiptsDetectorV1
 )
 
 # Print a full summary of the parsed data in RST format

data/docs/code_samples/passport_v1.txt

@@ -6,7 +6,7 @@
 require 'mindee'
 
 # Init a new client
-mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+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')
@@ -14,7 +14,7 @@ input_source = mindee_client.source_from_path('/path/to/the/file.ext')
 # Parse the file
 result = mindee_client.parse(
   input_source,
-  Mindee::Product::Passport::PassportV1
+  Mindee::V1::Product::Passport::PassportV1
 )
 
 # Print a full summary of the parsed data in RST format

data/docs/code_samples/resume_v1_async.txt

@@ -6,7 +6,7 @@
 require 'mindee'
 
 # Init a new client
-mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+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')
@@ -14,7 +14,7 @@ input_source = mindee_client.source_from_path('/path/to/the/file.ext')
 # Parse the file
 result = mindee_client.parse(
   input_source,
-  Mindee::Product::Resume::ResumeV1
+  Mindee::V1::Product::Resume::ResumeV1
 )
 
 # Print a full summary of the parsed data in RST format

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

@@ -8,7 +8,7 @@ require 'mindee'
 workflow_id = 'workflow-id'
 
 # Init a new client
-mindee_client = Mindee::Client.new
+mindee_client = Mindee::V1::Client.new
 
 # Load a file from disk
 input_source = mindee_client.source_from_path('path/to/my/file.ext')
@@ -19,7 +19,7 @@ result = mindee_client.execute_workflow(
   workflow_id,
 # options: { # Optionally, you can provide the following parameters:
 #   document_alias: 'my-document-alias', # Potential alias for the document
-#   priority: Mindee::Parsing::Common::ExecutionPriority::LOW, # Priority of the execution
+#   priority: Mindee::V1::Parsing::Common::ExecutionPriority::LOW, # Priority of the execution
 #   rag: true # Whether to enable Retrieval-Augmented Generation
 # }
 )

data/docs/code_samples/workflow_polling.txt

@@ -8,7 +8,7 @@ require 'mindee'
 workflow_id = 'workflow-id'
 
 # Init a new client
-mindee_client = Mindee::Client.new
+mindee_client = Mindee::V1::Client.new
 
 # Load a file from disk
 input_source = mindee_client.source_from_path('path/to/my/file.ext')
@@ -23,7 +23,7 @@ custom_endpoint = mindee_client.create_endpoint(
 # Parse the file
 result = mindee_client.parse(
   input_source,
-  Mindee::Product::Universal::Universal,
+  Mindee::V1::Product::Universal::Universal,
   endpoint: custom_endpoint,
   options: {
     rag: true,
@@ -33,4 +33,3 @@ result = mindee_client.parse(
 
 # Print a full summary of the parsed data in RST format
 puts result.document
-

data/examples/auto_invoice_splitter_extraction.rb

@@ -3,10 +3,10 @@
 require 'mindee'
 
 def invoice_splitter_auto_extraction(file_path)
-  mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+  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.count_pages > 1
+  if input_source.pdf? && input_source.page_count > 1
     parse_multi_page(mindee_client, input_source)
   else
     parse_single_page(mindee_client, input_source)
@@ -16,16 +16,16 @@ end
 def parse_single_page(mindee_client, input_source)
   invoice_result = mindee_client.parse(
     input_source,
-    Mindee::Product::Invoice::InvoiceV4
+    Mindee::V1::Product::Invoice::InvoiceV4
   )
   puts invoice_result.document
 end
 
 def parse_multi_page(mindee_client, input_source)
-  pdf_extractor = Mindee::PDF::PDFExtractor::PDFExtractor.new(input_source)
+  pdf_extractor = Mindee::PDF::PDFExtractor.new(input_source)
   invoice_splitter_response = mindee_client.parse(
     input_source,
-    Mindee::Product::InvoiceSplitter::InvoiceSplitterV1,
+    Mindee::V1::Product::InvoiceSplitter::InvoiceSplitterV1,
     options: { close_file: false }
   )
   page_groups = invoice_splitter_response.document.inference.prediction.invoice_page_groups
@@ -37,7 +37,7 @@ def parse_multi_page(mindee_client, input_source)
 
     invoice_result = mindee_client.parse(
       extracted_pdf.as_input_source,
-      Mindee::Product::Invoice::InvoiceV4,
+      Mindee::V1::Product::Invoice::InvoiceV4,
       options: { close_file: false }
     )
     puts invoice_result.document

data/examples/auto_multi_receipts_detector_extraction.rb

@@ -2,24 +2,24 @@
 
 require 'mindee'
 
-mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+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::Product::MultiReceiptsDetector::MultiReceiptsDetectorV1,
+    Mindee::V1::Product::MultiReceiptsDetector::MultiReceiptsDetectorV1,
     options: { close_file: false }
   )
 
-  images = Mindee::Extraction.extract_receipts(input_source, result_multi_receipts.document.inference)
+  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::Product::Receipt::ReceiptV5,
+      Mindee::V1::Product::Receipt::ReceiptV5,
       options: { close_file: false }
     )
     puts result_receipt.document

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/point.rb

@@ -31,6 +31,11 @@ module Mindee
           throw '0 or 1 only'
         end
       end
+
+      # @return [String] Point as a string.
+      def to_s
+        "(#{@x},#{@y})"
+      end
     end
   end
 end

data/lib/mindee/geometry/polygon.rb

@@ -7,7 +7,7 @@ module Mindee
     class Polygon < Array
       # @param server_response [Hash] Raw server response hash.
       def initialize(server_response)
-        points = []
+        points = [] # @type var points: Array[Mindee::Geometry::Point]
         server_response.map do |point|
           points << Point.new(point[0], point[1])
         end
@@ -27,6 +27,11 @@ module Mindee
         min_max = Geometry.get_min_max_y(self)
         point.y.between?(min_max.min, min_max.max)
       end
+
+      # @return [String] Polygon as a string.
+      def to_s
+        "(#{join(', ')})"
+      end
     end
   end
 end

data/lib/mindee/http/.rubocop.yml

@@ -5,4 +5,3 @@ Metrics/CyclomaticComplexity:
 
 Metrics/PerceivedComplexity:
   Max: 10
-

data/lib/mindee/http/http_error_handler.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
-require_relative '../errors/mindee_http_error'
+require_relative '../error/mindee_http_error'
 
 module Mindee
   module HTTP
@@ -81,11 +81,11 @@ module Mindee
         error_obj = create_error_obj(parsed_hash)
         case code
         when 400..499
-          Errors::MindeeHTTPClientError.new(error_obj || {}, url, code)
+          Error::MindeeHTTPClientError.new(error_obj || {}, url, code)
         when 500..599
-          Errors::MindeeHTTPServerError.new(error_obj || {}, url, code)
+          Error::MindeeHTTPServerError.new(error_obj || {}, url, code)
         else
-          Errors::MindeeHTTPError.new(error_obj || {}, url, code)
+          Error::MindeeHTTPError.new(error_obj || {}, url, code)
         end
       end
 
@@ -94,11 +94,11 @@ module Mindee
       def generate_v2_error(hashed_response)
         code = hashed_response[:code].to_i
         if hashed_response.key?(:status)
-          Errors::MindeeHTTPErrorV2.new(hashed_response.transform_keys(&:to_s))
+          Error::MindeeHTTPErrorV2.new(hashed_response.transform_keys(&:to_s))
         elsif code < 200 || code > 399
-          Errors::MindeeHTTPErrorV2.new({ 'status' => code, 'detail' => 'No details available.' })
+          Error::MindeeHTTPErrorV2.new({ 'status' => code, 'detail' => 'No details available.' })
         else
-          Errors::MindeeHTTPErrorV2.new({ 'status' => -1, 'detail' => 'Unknown Error.' })
+          Error::MindeeHTTPErrorV2.new({ 'status' => -1, 'detail' => 'Unknown Error.' })
         end
       end
     end

data/lib/mindee/http/response_validation.rb

@@ -51,7 +51,7 @@ module Mindee
 
         hashed_response = JSON.parse(response.body, object_class: Hash)
 
-        return false if hashed_response.dig('job', 'status') == Mindee::Parsing::Common::JobStatus::FAILURE
+        return false if hashed_response.dig('job', 'status') == Mindee::V1::Parsing::Common::JobStatus::FAILURE
 
         return false if hashed_response.dig('job', 'error') && !hashed_response.dig('job', 'error').empty?
 
@@ -71,7 +71,8 @@ module Mindee
         end
 
         return if !hashed_response.dig('job', 'error').empty? &&
-                  (hashed_response.dig('job', 'status').downcase != Mindee::Parsing::Common::JobStatus::FAILURE.to_s)
+                  (hashed_response.dig('job',
+                                       'status').downcase != Mindee::V1::Parsing::Common::JobStatus::FAILURE.to_s)
 
         response.instance_variable_set(:@code, '500')
       end