mindee 4.12.0 → 4.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ec6f37e83f30ed06cca64a016ea4936211726fe0e4e6281f6e9eec42f32bfdc
-  data.tar.gz: 780f641de505dcb64842c73b2597d389894522f38c345d92c2b28fd52db61749
+  metadata.gz: 8e4f8318f4cd6905b0b6b0085cbf9408bee1fe3445cab4b131415d21b7e4edad
+  data.tar.gz: 013a22e77863832af297cb477fac58225372d88e5eae7ea07761e310f3d0bfb0
 SHA512:
-  metadata.gz: f0909570d17dfcc54d8d95671ec323c733a98be640bd71c837708759a623d16896133998f2e5af67aa845420f92ef7c6c875d9890c6e8e9dbe97db0069529f73
-  data.tar.gz: '0975d445b49f5e22805baec50eebbaf2e8127fd85ab22fe5970167eeb3d31217be2db50ddc6a56155580d70f5fbce888f4b491d58343d7fc3fea806ed5de0d33'
+  metadata.gz: 0cae355f24d35edf36b1decb45131efeb7655a3e0a5d92938007086f1ec3d5f93dbc6e5ef96018fc20fb079ad42f91e8659848f7cf40e57add8e2547436ea662
+  data.tar.gz: f2e4b632ec7ded0cd42b8ff3d66ca066034d201d398fd46833a123c17e4b342c55fb533379234bff325b5a6bb2e24a64252b2988aaae2eafc79a2a03f1136811

data/.gitignore

@@ -16,6 +16,8 @@
 /test/version_tmp/
 /tmp/
 _test.rb
+_test_v1.rb
+_test_v2.rb
 /vendor
 /mindee-*/
 local-test

data/.rubocop.yml

@@ -6,7 +6,7 @@ AllCops:
     - 'tmp/**/*'
     - '.git/**/*'
     - 'bin/*'
-    - _test.rb
+    - _test*.rb
     - local_test/*
     - Steepfile
 

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Mindee Ruby API Library Changelog
 
+## v4.13.0 - 2026-03-03
+### Changes
+* :sparkles: add support for V2 Classification product
+* :sparkles: add support for V2 Crop product
+* :sparkles: add support for V2 Ocr product
+* :sparkles: add support for V2 Split product
+* :recycle: make polling follow API urls instead of re-constructing them
+* :sparkles: add support for generic product accessors in V2
+* :recycle: add proper tests for ruby 4
+### Fixes 
+* :recycle: fix tests file paths 
+
+
 ## v4.12.0 - 2026-02-25
 ### Changes
 * :sparkles: add job information to inference

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::ClientV2.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::ClientV2.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/{default_v2.txt → v2_extraction.txt}

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'mindee'
+require 'mindee/v2/product'
 
 input_path = '/path/to/the/file.ext'
 api_key = 'MY_API_KEY'
@@ -10,9 +11,9 @@ model_id = 'MY_MODEL_ID'
 mindee_client = Mindee::ClientV2.new(api_key: api_key)
 
 # Set inference parameters
-inference_params = Mindee::Input::InferenceParameters.new(
+inference_params = {
     # ID of the model, required.
-    model_id,
+    model_id: model_id,
 
     # Options: set to `true` or `false` to override defaults
 
@@ -25,15 +26,16 @@ inference_params = Mindee::Input::InferenceParameters.new(
     # 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_inference(
+response = mindee_client.enqueue_and_get_result(
+    Mindee::V2::Product::Extraction::Extraction,
     input_source,
-    inference_params # This parameter can also be provided as a Hash.
+    inference_params
 )
 
 # Print a brief summary of the parsed data

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::ClientV2.new(api_key: api_key)
+
+inference_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,
+    inference_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::ClientV2.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::ClientV2.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/lib/mindee/client_v2.rb

@@ -26,8 +26,16 @@ module Mindee
       @mindee_api.req_get_inference(inference_id)
     end
 
-    # Retrieves an inference.
-    # @param job_id [String]
+    # Retrieves a result from a given queue or URL to the result.
+    # @param product [Class<Mindee::V2::Product::BaseProduct>] The return class.
+    # @param resource [String] ID of the inference or URL to the result.
+    # @return [Mindee::Parsing::V2::BaseResponse]
+    def get_result(product, resource)
+      @mindee_api.req_get_result(product, resource)
+    end
+
+    # Retrieves an inference from a given queue or URL to the job.
+    # @param job_id [String] ID of the job.
     # @return [Mindee::Parsing::V2::JobResponse]
     def get_job(job_id)
       @mindee_api.req_get_job(job_id)
@@ -38,22 +46,47 @@ module Mindee
     #   The source of the input document (local file or URL).
     # @param params [Hash, InferenceParameters]
     # @return [Mindee::Parsing::V2::JobResponse]
-    def enqueue_inference(input_source, params)
-      normalized_params = normalize_inference_parameters(params)
+    def enqueue_inference(input_source, params, disable_redundant_warnings: false)
+      unless disable_redundant_warnings
+        warn '[DEPRECATION] `enqueue_inference` is deprecated; use `enqueue` instead.', uplevel: 1
+      end
+      normalized_params = normalize_parameters(Input::InferenceParameters, params)
+      enqueue(Mindee::Parsing::V2::Inference, input_source, normalized_params)
+    end
+
+    # Enqueue a document for async parsing.
+    # @param product [Class<Mindee::V2::Product::BaseProduct>] The return class.
+    # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
+    #   The source of the input document (local file or URL).
+    # @param params [Hash, InferenceParameters] Parameters for the inference.
+    # @return [Mindee::Parsing::V2::JobResponse]
+    def enqueue(
+      product,
+      input_source,
+      params
+    )
+      normalized_params = normalize_parameters(product.params_type, params)
+      normalized_params.validate_async_params
       logger.debug("Enqueueing document to model '#{normalized_params.model_id}'.")
 
-      @mindee_api.req_post_inference_enqueue(input_source, normalized_params)
+      @mindee_api.req_post_enqueue(input_source, normalized_params)
     end
 
-    # Enqueue a document for async parsing and automatically try to retrieve it.
+    # Enqueues to an asynchronous endpoint and automatically polls for a response.
+    #
+    # @param product [Class<Mindee::V2::Product::BaseProduct>] The return class.
     # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
     #   The source of the input document (local file or URL).
     # @param params [Hash, InferenceParameters] Parameters for the inference.
-    # @return [Mindee::Parsing::V2::InferenceResponse]
-    def enqueue_and_get_inference(input_source, params)
-      normalized_params = normalize_inference_parameters(params)
+    # @return [Mindee::Parsing::Common::ApiResponse]
+    def enqueue_and_get_result(
+      product,
+      input_source,
+      params
+    )
+      enqueue_response = enqueue(product, input_source, params)
+      normalized_params = normalize_parameters(product.params_type, params)
       normalized_params.validate_async_params
-      enqueue_response = enqueue_inference(input_source, normalized_params)
 
       if enqueue_response.job.id.nil? || enqueue_response.job.id.empty?
         logger.error("Failed enqueueing:\n#{enqueue_response.raw_http}")
@@ -70,8 +103,8 @@ module Mindee
       while retry_counter < normalized_params.polling_options.max_retries
         if poll_results.job.status == 'Failed'
           break
-        elsif poll_results.job.status == 'Processed'
-          return get_inference(poll_results.job.id)
+        elsif !poll_results.job.result_url.nil?
+          return get_result(product, poll_results.job.result_url)
         end
 
         logger.debug(
@@ -97,13 +130,32 @@ module Mindee
             "Asynchronous parsing request timed out after #{sec_count} seconds"
     end
 
+    # Enqueue a document for async parsing and automatically try to retrieve it.
+    # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
+    #   The source of the input document (local file or URL).
+    # @param params [Hash, InferenceParameters] Parameters for the inference.
+    # @return [Mindee::Parsing::V2::InferenceResponse]
+    def enqueue_and_get_inference(input_source, params, disable_redundant_warnings: false)
+      unless disable_redundant_warnings
+        warn '[DEPRECATION] `enqueue_and_get_inference` is deprecated; use `enqueue_and_get_result` instead.',
+             uplevel: 1
+      end
+
+      response = enqueue_and_get_result(Mindee::Parsing::V2::Inference, input_source, params)
+      unless response.is_a?(Mindee::Parsing::V2::InferenceResponse)
+        raise TypeError, "Invalid response type \"#{response.class}\""
+      end
+
+      response
+    end
+
     # If needed, converts the parsing options provided as a hash into a proper InferenceParameters object.
-    # @param params [Hash, InferenceParameters] Params.
-    # @return [InferenceParameters]
-    def normalize_inference_parameters(params)
-      return params if params.is_a?(Input::InferenceParameters)
+    # @param params [Hash, Class<BaseParameters>] Params.
+    # @return [BaseParameters]
+    def normalize_parameters(param_class, params)
+      return param_class.from_hash(params: params) if params.is_a?(Hash)
 
-      Input::InferenceParameters.from_hash(params: params)
+      params
     end
   end
 end

data/lib/mindee/errors/mindee_http_error_v2.rb

@@ -18,7 +18,7 @@ module Mindee
       # @return [Array<ErrorItem>] A list of explicit error details.
       attr_reader :errors
 
-      # @param http_error [Hash, Parsing::V2::ErrorResponse]
+      # @param http_error [Hash, Mindee::Parsing::V2::ErrorResponse]
       def initialize(http_error)
         if http_error.is_a?(Parsing::V2::ErrorResponse)
           http_error = { 'detail' => http_error.detail,
@@ -33,7 +33,7 @@ module Mindee
         @code = http_error['code']
         @errors = if http_error.key?('errors')
                     http_error['errors'].map do |error|
-                      Parsing::V2::ErrorItem.new(error)
+                      Mindee::Parsing::V2::ErrorItem.new(error)
                     end
                   else
                     []

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

@@ -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
+        "(#{map(&:to_s).join(', ')})"
+      end
     end
   end
 end

data/lib/mindee/http/mindee_api_v2.rb

@@ -20,16 +20,16 @@ module Mindee
       # Sends a file to the inference queue.
       #
       # @param input_source [Input::Source::LocalInputSource, Input::Source::URLInputSource]
-      # @param params [Input::InferenceParameters]
+      # @param params [Input::BaseParameters]
       # @return [Mindee::Parsing::V2::JobResponse]
       # @raise [Mindee::Errors::MindeeHttpErrorV2]
-      def req_post_inference_enqueue(input_source, params)
+      def req_post_enqueue(input_source, params)
         @settings.check_api_key
         response = enqueue(
           input_source,
           params
         )
-        Parsing::V2::JobResponse.new(process_response(response))
+        Mindee::Parsing::V2::JobResponse.new(process_response(response))
       end
 
       # Retrieves a queued inference.
@@ -37,27 +37,69 @@ module Mindee
       # @param inference_id [String]
       # @return [Mindee::Parsing::V2::InferenceResponse]
       def req_get_inference(inference_id)
+        req_get_result(Parsing::V2::Inference, inference_id)
+      end
+
+      # Retrieves a result from a given queue.
+      # @param product [Class<Mindee::V2::Product::BaseProduct>] The return class.
+      # @param resource [String] ID of the inference or URL to the result.
+      # @return [Mindee::Parsing::V2::BaseResponse]
+      def req_get_result(product, resource)
+        return req_get_result_url(product.response_type, resource) if uri?(resource)
+
         @settings.check_api_key
-        response = inference_result_req_get(
-          inference_id
+        response = result_req_get(
+          resource,
+          product
         )
-        Parsing::V2::InferenceResponse.new(process_response(response))
+        product.response_type.new(process_response(response))
       end
 
       # Retrieves a queued job.
       #
-      # @param job_id [String]
+      # @param job_id [String] ID of the job or URL to the job.
       # @return [Mindee::Parsing::V2::JobResponse]
       def req_get_job(job_id)
         @settings.check_api_key
         response = inference_job_req_get(
           job_id
         )
-        Parsing::V2::JobResponse.new(process_response(response))
+        Mindee::Parsing::V2::JobResponse.new(process_response(response))
       end
 
       private
 
+      # Retrieves a queued job.
+      #
+      # @param url [String]
+      # @return [Mindee::Parsing::V2::JobResponse]
+      def req_get_job_url(url)
+        @settings.check_api_key
+        response = poll(url)
+        Mindee::Parsing::V2::JobResponse.new(process_response(response))
+      end
+
+      # Retrieves a queued job.
+      #
+      # @param result_class [Mindee::V2::Parsing::BaseResponse]
+      # @param url [String]
+      # @return [Mindee::Parsing::V2::JobResponse]
+      def req_get_result_url(result_class, url)
+        @settings.check_api_key
+        response = poll(url)
+        result_class.new(process_response(response))
+      end
+
+      # @param resource [String] Resource to check.
+      # @return [Boolean]
+      def uri?(resource)
+        uri = URI.parse(resource)
+        throw Mindee::Errors::MindeeError, 'HTTP is not supported.' if uri.scheme == 'http'
+        uri.scheme == 'https'
+      rescue URI::BadURIError, URI::InvalidURIError
+        false
+      end
+
       # Converts an HTTP response to a parsed response object.
       #
       # @param response [Net::HTTPResponse, nil]
@@ -111,6 +153,15 @@ module Mindee
         poll("#{@settings.base_url}/inferences/#{queue_id}")
       end
 
+      # Polls the API for the result of an inference.
+      #
+      # @param queue_id [String] ID of the queue.
+      # @param product [Class<Mindee::V2::Product::BaseProduct>] The return class.
+      # @return [Net::HTTPResponse]
+      def result_req_get(queue_id, product)
+        poll("#{@settings.base_url}/products/#{product.slug}/results/#{queue_id}")
+      end
+
       # Handle parameters for the enqueue form
       # @param form_data [Array] Array of form fields
       # @param params [Input::InferenceParameters] Inference options.
@@ -130,10 +181,10 @@ module Mindee
       end
 
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
-      # @param params [Input::InferenceParameters] Inference options.
+      # @param params [Input::BaseParameters] Inference options.
       # @return [Net::HTTPResponse, nil]
       def enqueue(input_source, params)
-        uri = URI("#{@settings.base_url}/inferences/enqueue")
+        uri = URI("#{@settings.base_url}/products/#{params.slug}/enqueue")
 
         form_data = if input_source.is_a?(Mindee::Input::Source::URLInputSource)
                       [['url', input_source.url]] # : Array[untyped]
@@ -143,8 +194,7 @@ module Mindee
                     end
         form_data.push(['model_id', params.model_id])
 
-        # deal with other parameters
-        form_data = enqueue_form_options(form_data, params)
+        form_data = params.append_form_data(form_data)
 
         headers = {
           'Authorization' => @settings.api_key,