✨ add support for Client V2 (#194)

Author: sebastianMindee

.github/workflows/_test-code-samples.yml

@@ -32,4 +32,4 @@ jobs:
         env:
           MINDEE_LOG_LEVEL: DEBUG
         run: |
-            ./spec/test_code_samples.sh ${{ secrets.MINDEE_ACCOUNT_SE_TESTS }} ${{ secrets.MINDEE_ENDPOINT_SE_TESTS }} ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
+            ./spec/test_code_samples.sh ${{ secrets.MINDEE_ACCOUNT_SE_TESTS }} ${{ secrets.MINDEE_ENDPOINT_SE_TESTS }} ${{ secrets.MINDEE_API_KEY_SE_TESTS }} ${{ secrets.MINDEE_V2_SE_TESTS_API_KEY }} ${{ secrets.MINDEE_V2_SE_TESTS_FINDOC_MODEL_ID }}

.github/workflows/_test-integrations.yml

@@ -56,6 +56,9 @@ jobs:
         env:
           MINDEE_API_KEY: ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
           WORKFLOW_ID: ${{ secrets.WORKFLOW_ID_SE_TESTS }}
+          MINDEE_V2_API_KEY: ${{ secrets.MINDEE_V2_SE_TESTS_API_KEY }}
+          MINDEE_V2_FINDOC_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_FINDOC_MODEL_ID }}
+          MINDEE_V2_SE_TESTS_BLANK_PDF_URL: ${{ secrets.MINDEE_V2_SE_TESTS_BLANK_PDF_URL }}
           MINDEE_LOG_LEVEL: DEBUG
         run: |
           bundle exec rake integration

.github/workflows/pull-request.yml

@@ -3,18 +3,22 @@ name: Pull Request
 on:
   pull_request:
 
+permissions:
+  contents: read
+  pull-requests: read
+
 jobs:
   static_analysis:
-    uses: mindee/mindee-api-ruby/.github/workflows/_static-analysis.yml@main
+    uses: ./.github/workflows/_static-analysis.yml
   test_units:
-    uses: mindee/mindee-api-ruby/.github/workflows/_test-units.yml@main
+    uses: ./.github/workflows/_test-units.yml
     needs: static_analysis
     secrets: inherit
   test_integrations:
-    uses: mindee/mindee-api-ruby/.github/workflows/_test-integrations.yml@main
+    uses: ./.github/workflows/_test-integrations.yml
     needs: test_units
     secrets: inherit
   test_code_samples:
-    uses: mindee/mindee-api-ruby/.github/workflows/_test-code-samples.yml@main
+    uses: ./.github/workflows/_test-code-samples.yml
     needs: test_units
     secrets: inherit

docs/code_samples/default_v2.txt

@@ -0,0 +1,28 @@
+require 'mindee'
+
+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
+params = Mindee::Input::InferenceParameters.new(
+    # ID of the model, required.
+    model_id,
+    # If set to `True`, will enable Retrieval-Augmented Generation.
+    rag: false,
+)
+
+# Load a file from disk
+input_source = Mindee::Input::Source::PathInputSource.new(input_path)
+
+# Send for processing
+response = mindee_client.enqueue_and_get_inference(
+    input_source,
+    params # Note: this parameter can also be provided as a Hash.
+)
+
+# Print a brief summary of the parsed data
+puts response.inference

lib/mindee.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'mindee/client'
+require 'mindee/client_v2'
+require 'mindee/page_options'
 require 'mindee/logging'
 
 module Mindee
@@ -54,6 +56,10 @@ module Standard
     # Universal fields and functions.
     module Universal
     end
+
+    # V2-specific module.
+    module V2
+    end
   end
 
   # Document input-related internals.

lib/mindee/client.rb

@@ -2,38 +2,17 @@
 
 require_relative 'input'
 require_relative 'http'
-require_relative 'product'
+require_relative 'logging'
+require_relative 'page_options'
 require_relative 'parsing/common/api_response'
 require_relative 'parsing/common/job'
 require_relative 'parsing/common/workflow_response'
-require_relative 'logging'
+require_relative 'product'
 
 # Default owner for products.
 OTS_OWNER = 'mindee'
 
 module Mindee
-  # Class for page options in parse calls.
-  #
-  # @!attribute page_indexes [Array[Integer]] Zero-based list of page indexes.
-  # @!attribute operation [:KEEP_ONLY, :REMOVE] Operation to apply on the document, given the specified page indexes:
-  #   * `:KEEP_ONLY` - keep only the specified pages, and remove all others.
-  #   * `:REMOVE` - remove the specified pages, and keep all others.
-  # @!attribute on_min_pages [Integer, nil] Apply the operation only if the document has at least this many pages.
-  class PageOptions
-    attr_accessor :page_indexes, :operation, :on_min_pages
-
-    def initialize(params: {})
-      params ||= {}
-      params = params.transform_keys(&:to_sym)
-      @page_indexes = params.fetch(
-        :page_indexes,
-        [] # : Array[Integer]
-      )
-      @operation    = params.fetch(:operation, :KEEP_ONLY)
-      @on_min_pages = params.fetch(:on_min_pages, nil)
-    end
-  end
-
   # Class for configuration options in parse calls.
   #
   # @!attribute all_words [bool] Whether to include the full text for each page.
@@ -89,8 +68,9 @@ def initialize(params: {})
   #       * `:KEEP_ONLY` - keep only the specified pages, and remove all others.
   #       * `:REMOVE` - remove the specified pages, and keep all others.
   #   * `:on_min_pages` Apply the operation only if the document has at least this many pages.
+  # @!attribute close_file [bool, nil] Whether to close the file after sending it. Defaults to true.
   class WorkflowOptions
-    attr_accessor :document_alias, :priority, :full_text, :public_url, :page_options, :rag
+    attr_accessor :document_alias, :priority, :full_text, :public_url, :page_options, :rag, :close_file
 
     def initialize(params: {})
       params = params.transform_keys(&:to_sym)
@@ -102,6 +82,7 @@ def initialize(params: {})
       raw_page_options = params.fetch(:page_options, nil)
       raw_page_options = PageOptions.new(params: raw_page_options) unless raw_page_options.is_a?(PageOptions)
       @page_options = raw_page_options
+      @close_file = params.fetch(:close_file, true)
     end
   end
 
@@ -326,7 +307,7 @@ def execute_workflow(input_source, workflow_id, options: {})
         process_pdf_if_required(input_source, opts)
       end
 
-      workflow_endpoint = Mindee::HTTP::WorkflowEndpoint.new(workflow_id, api_key: @api_key)
+      workflow_endpoint = Mindee::HTTP::WorkflowEndpoint.new(workflow_id, api_key: @api_key.to_s)
       logger.debug("Sending document to workflow '#{workflow_id}'")
 
       prediction, raw_http = workflow_endpoint.execute_workflow(
@@ -455,11 +436,11 @@ def initialize_endpoint(product_class, endpoint_name: '', account_name: '', vers
       account_name = fix_account_name(account_name)
       version = fix_version(product_class, version)
 
-      HTTP::Endpoint.new(account_name, endpoint_name, version, api_key: @api_key)
+      HTTP::Endpoint.new(account_name, endpoint_name, version, api_key: @api_key.to_s)
     end
 
     def fix_endpoint_name(product_class, endpoint_name)
-      endpoint_name.nil? || endpoint_name.empty? ? product_class.endpoint_name : endpoint_name
+      endpoint_name.nil? || endpoint_name.empty? ? product_class.endpoint_name.to_s : endpoint_name.to_s
     end
 
     def fix_account_name(account_name)
@@ -474,11 +455,11 @@ def fix_account_name(account_name)
     def fix_version(product_class, version)
       return version unless version.nil? || version.empty?
 
-      if product_class.endpoint_version.nil? || product_class.endpoint_version.empty?
+      if product_class.endpoint_version.nil? || product_class.endpoint_version.to_s.empty?
         logger.debug('No version provided for a custom build, will attempt to poll version 1 by default.')
         return '1'
       end
-      product_class.endpoint_version
+      product_class.endpoint_version || ''
     end
 
     # If needed, converts the parsing options provided as a hash into a proper ParseOptions object.

lib/mindee/client_v2.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative 'input'
+require_relative 'http'
+require_relative 'product'
+require_relative 'parsing/common/api_response'
+require_relative 'parsing/common/job'
+require_relative 'parsing/common/workflow_response'
+require_relative 'logging'
+
+module Mindee
+  # Mindee V2 API Client.
+  class ClientV2
+    # @return [HTTP::MindeeApiV2]
+    private attr_reader :mindee_api
+
+    # @param api_key [String]
+    def initialize(api_key: '')
+      @mindee_api = Mindee::HTTP::MindeeApiV2.new(api_key: api_key)
+    end
+
+    # Retrieves an inference.
+    # @param inference_id [String]
+    # @return [Mindee::Parsing::V2::InferenceResponse]
+    def get_inference(inference_id)
+      @mindee_api.req_get_inference(inference_id)
+    end
+
+    # Retrieves an inference.
+    # @param job_id [String]
+    # @return [Mindee::Parsing::V2::JobResponse]
+    def get_job(job_id)
+      @mindee_api.req_get_job(job_id)
+    end
+
+    # Enqueue a document for async parsing.
+    # @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]
+    # @return [Mindee::Parsing::V2::JobResponse]
+    def enqueue_inference(input_source, params)
+      normalized_params = normalize_inference_parameters(params)
+      logger.debug("Enqueueing document to model '#{normalized_params.model_id}'.")
+
+      @mindee_api.req_post_inference_enqueue(input_source, normalized_params)
+    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)
+      normalized_params = normalize_inference_parameters(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}")
+        raise Mindee::Errors::MindeeError, 'Enqueueing of the document failed.'
+      end
+
+      job_id = enqueue_response.job.id
+      logger.debug("Successfully enqueued document with job id: #{job_id}.")
+
+      sleep(normalized_params.polling_options.initial_delay_sec)
+      retry_counter = 1
+      poll_results = get_job(job_id)
+
+      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)
+        end
+
+        logger.debug(
+          "Successfully enqueued inference with job id: #{job_id}.\n" \
+          "Attempt n°#{retry_counter}/#{normalized_params.polling_options.max_retries}.\n" \
+          "Job status: #{poll_results.job.status}."
+        )
+
+        sleep(normalized_params.polling_options.delay_sec)
+        poll_results = get_job(job_id)
+        retry_counter += 1
+      end
+
+      error = poll_results.job.error
+      unless error.nil?
+        err_to_raise = Mindee::Errors::MindeeHTTPErrorV2.new(error)
+        # NOTE: purposefully decoupled from the line above, otherwise rubocop thinks `error` is a `message` param.
+        raise err_to_raise
+      end
+
+      sec_count = normalized_params.polling_options.delay_sec * retry_counter
+      raise Mindee::Errors::MindeeError,
+            "Asynchronous parsing request timed out after #{sec_count} seconds"
+    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)
+
+      Input::InferenceParameters.from_hash(params: params)
+    end
+  end
+end

lib/mindee/errors.rb

@@ -2,4 +2,5 @@
 
 require_relative 'errors/mindee_error'
 require_relative 'errors/mindee_http_error'
+require_relative 'errors/mindee_http_error_v2'
 require_relative 'errors/mindee_input_error'

lib/mindee/errors/mindee_http_error_v2.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'mindee_error'
+
+module Mindee
+  module Errors
+    # API V2 HttpError
+    class MindeeHTTPErrorV2 < MindeeError
+      # @return [Integer]
+      attr_reader :status
+      # @return [String]
+      attr_reader :detail
+
+      # @param http_error [Hash, Parsing::V2::ErrorResponse]
+      def initialize(http_error)
+        if http_error.is_a?(Parsing::V2::ErrorResponse)
+          http_error = { 'detail' => http_error.detail,
+                         'status' => http_error.status }
+        end
+        @status = http_error['status']
+        @detail = http_error['detail']
+        super("HTTP error: #{@status} - #{@detail}")
+      end
+    end
+  end
+end

lib/mindee/geometry/point.rb

@@ -6,9 +6,9 @@ module Geometry
     # A relative set of coordinates (X, Y) on the document.
     class Point
       # @return [Float]
-      attr_accessor :x
+      attr_reader :x
       # @return [Float]
-      attr_accessor :y
+      attr_reader :y
 
       # rubocop:disable Naming/MethodParameterName