mindee-lite 5.4.0 → 5.5.0

data/lib/mindee/v2/client_options/base_product_parameters.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V2
+    module ClientOptions
+      # Base class for parameters accepted by all V2 endpoints.
+      class BaseProductParameters
+        # @return [String] Model ID to use for the inference. Required.
+        attr_reader :model_id
+
+        # @return [String, nil] Optional: a free-form string to tag the request with your own identifier.
+        # For example, an internal document ID, reference number, or database key.
+        # If set, it will be included in the job and result responses.
+        attr_reader :file_alias
+
+        # @return [Array<String>, nil] Webhook IDs to call after all processing is finished.
+        # If empty, no webhooks will be used.
+        attr_reader :webhook_ids
+
+        # @return [Input::PollingOptions] Options for polling. Set only if having timeout issues.
+        attr_reader :polling_options
+
+        # @return [Boolean, nil] Whether to close the file after parsing.
+        attr_reader :close_file
+
+        # @param [String] model_id ID of the model
+        # @param [String, nil] file_alias File alias, if applicable.
+        # @param [Array<String>, nil] webhook_ids List of webhook IDs to propagate the API response to.
+        # @param [Hash, Input::PollingOptions, nil] polling_options Options for polling. Set only if having timeout
+        # issues.
+        # @param [Boolean, nil] close_file Whether to close the file after parsing.
+        def initialize(
+          model_id,
+          file_alias: nil,
+          webhook_ids: nil,
+          polling_options: nil,
+          close_file: true
+        )
+          raise Error::MindeeInputError, 'Model ID is required.' if model_id.nil? || model_id.empty?
+
+          @model_id = model_id
+          @file_alias = file_alias
+          @webhook_ids = webhook_ids || []
+          @polling_options = get_clean_polling_options(polling_options)
+          @close_file = close_file.nil? || close_file
+        end
+
+        # Sets polling options after normalizing hash inputs.
+        # @param [Hash, Input::PollingOptions, nil] polling_options
+        # @return [Input::PollingOptions]
+        def polling_options=(polling_options)
+          @polling_options = get_clean_polling_options(polling_options)
+        end
+
+        # @return [String] Slug for the endpoint.
+        def self.slug
+          if self == BaseProductParameters
+            raise NotImplementedError, 'Cannot access `slug` directly on the BaseProductParameters class.'
+          end
+
+          ''
+        end
+
+        # @return [String] Slug for the endpoint.
+        def slug
+          self.class.slug
+        end
+
+        # Load from a hash
+        # @param [Hash] params Parameters to provide as a hash.
+        # @return [BaseProductParameters]
+        def self.from_hash(params: {})
+          load_from_hash(params: params)
+          new(
+            params[:model_id],
+            file_alias: params[:file_alias],
+            webhook_ids: params[:webhook_ids],
+            polling_options: params[:polling_options],
+            close_file: params[:close_file]
+          )
+        end
+
+        # Loads a prediction from a Hash.
+        # @param [Hash] params Parameters to provide as a hash.
+        # @return [Hash]
+        def self.load_from_hash(params: {})
+          params.transform_keys!(&:to_sym)
+
+          if params.empty? || params[:model_id].nil? || params[:model_id].empty?
+            raise Error::MindeeInputError, 'Model ID is required.'
+          end
+
+          polling_options_input = params.fetch(:page_options, Input::PollingOptions.new)
+          if polling_options_input.is_a?(Hash)
+            polling_options_input = polling_options_input.transform_keys(&:to_sym)
+            Input::PollingOptions.new(
+              initial_delay_sec: polling_options_input.fetch(:initial_delay_sec, 2.0),
+              delay_sec: polling_options_input.fetch(:delay_sec, 1.5),
+              max_retries: polling_options_input.fetch(:max_retries, 80)
+            )
+          end
+          params
+        end
+
+        # Appends base form data to the provided array.
+        # @param [Array] form_data Array of form fields
+        # @return [Array]
+        def append_form_data(form_data)
+          form_data.push(['alias', @file_alias]) if @file_alias
+          webhook_ids = @webhook_ids || []
+          form_data.push(['webhook_ids', webhook_ids.join(',')]) unless @webhook_ids.nil? || webhook_ids.empty?
+          form_data
+        end
+
+        # Validates the parameters for async auto-polling
+        def validate_async_params
+          min_delay_sec = 1
+          min_initial_delay_sec = 1
+          min_retries = 2
+
+          if @polling_options.delay_sec < min_delay_sec
+            raise ArgumentError,
+                  "Cannot set auto-poll delay to less than #{min_delay_sec} second(s)"
+          end
+          if @polling_options.initial_delay_sec < min_initial_delay_sec
+            raise ArgumentError,
+                  "Cannot set initial parsing delay to less than #{min_initial_delay_sec} second(s)"
+          end
+          return unless @polling_options.max_retries < min_retries
+
+          raise ArgumentError,
+                "Cannot set auto-poll retries to less than #{min_retries}"
+        end
+
+        private
+
+        # Cleans a proper polling options object potentially from a hash.
+        # @param [Hash, Input::PollingOptions, nil] polling_options Polling options.
+        # @return [Input::PollingOptions] Valid polling options object.
+        def get_clean_polling_options(polling_options)
+          return Input::PollingOptions.new if polling_options.is_a?(Input::PollingOptions)
+
+          if polling_options.is_a?(Hash)
+            polling_options = polling_options.transform_keys(&:to_sym)
+            output_polling_options = Input::PollingOptions.new(
+              initial_delay_sec: polling_options.fetch(:initial_delay_sec, 2.0),
+              delay_sec: polling_options.fetch(:delay_sec, 1.5),
+              max_retries: polling_options.fetch(:max_retries, 80)
+            )
+          else
+            output_polling_options = if polling_options.is_a?(Input::PollingOptions)
+                                       polling_options || Input::PollingOptions.new
+                                     else
+                                       Input::PollingOptions.new
+                                     end
+          end
+          output_polling_options
+        end
+      end
+    end
+  end
+end

data/lib/mindee/v2/client_options/base_search_parameters.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V2
+    module ClientOptions
+      # Base parameters for searches.
+      class BaseSearchParameters
+        # @return [Integer, nil] 1-based page index.
+        attr_reader :page
+        # @return [Integer, nil] Number of items per page.
+        attr_reader :per_page
+
+        # @param page [Integer, nil] 1-based page index.
+        # @param per_page [Integer, nil] Number of items per page.
+        def initialize(page: nil, per_page: nil)
+          @page = page
+          @per_page = per_page
+        end
+
+        # Gets the request parameters for the search request.
+        # @return [Hash{String => String, Array<String>}]
+        def request_parameters
+          params = {} # : Hash[String, String | Array[String]]
+          params['page'] = @page.to_s unless @page.nil?
+          params['per_page'] = @per_page.to_s unless @per_page.nil?
+          params
+        end
+
+        # @return [String] Slug of searchable resources.
+        def self.slug
+          raise NotImplementedError, 'Subclasses must implement the `slug` class method'
+        end
+
+        # @return [String] Slug of searchable resources.
+        def slug
+          self.class.slug
+        end
+
+        # @return [Class<Mindee::V2::Parsing::Search::BaseSearchResponse>] Response class for the search.
+        def self.response_class
+          raise NotImplementedError, 'Subclasses must implement the `response_class` class method'
+        end
+
+        # @return [Class<Mindee::V2::Parsing::Search::BaseSearchResponse>] Response class for the search.
+        def response_class
+          self.class.response_class
+        end
+      end
+    end
+  end
+end

data/lib/mindee/v2/client_options.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'client_options/base_product_parameters'
+require_relative 'client_options/base_search_parameters'

data/lib/mindee/v2/http/mindee_api_v2.rb

@@ -17,13 +17,13 @@ module Mindee
           @settings = ApiV2Settings.new(api_key: api_key)
         end
 
-        # Sends a file to the queue.
+        # Send a file to the asynchronous processing queue for inference processing.
         #
         # @param input_source [Input::Source::LocalInputSource, Input::Source::URLInputSource]
-        # @param params [Input::BaseParameters]
+        # @param params [ClientOptions::BaseProductParameters]
         # @return [Mindee::V2::Parsing::JobResponse]
         # @raise [Mindee::Error::MindeeHttpErrorV2]
-        def req_post_enqueue(input_source, params)
+        def req_post_product_enqueue(input_source, params)
           @settings.check_api_key
           response = enqueue(
             input_source,
@@ -57,28 +57,15 @@ module Mindee
           Mindee::V2::Parsing::JobResponse.new(process_response(response))
         end
 
-        # Retrieves a list of models.
-        # @param model_name [String, nil]
-        # @param model_type [String, nil]
-        # @return [Mindee::V2::Parsing::Search::SearchResponse]
-        def search_models(model_name, model_type)
-          Mindee::V2::Parsing::Search::SearchResponse.new(process_response(req_get_search_models(model_name,
-                                                                                                 model_type)))
-        end
-
-        private
-
-        # Retrieves a list of models.
-        # @param model_name [String, nil]
-        # @param model_type [String, nil]
-        # @return [Net::HTTPResponse]
-        def req_get_search_models(model_name, model_type)
-          url = "#{@settings.base_url}/v2/search/models"
-          uri = URI(url)
+        # Retrieves a list of resources with the given criteria.
+        # @param params [ClientOptions::BaseSearchParameters] Search parameters.
+        # @return [Mindee::V2::Parsing::Search::BaseSearchResponse] A search response containing the matching
+        #   resources.
+        def req_get_search(params)
+          @settings.check_api_key
+          uri = URI("#{@settings.base_url}/v2/search/#{params.slug}")
 
-          query_params = {} # @type var query_params: Hash[Symbol, String | nil]
-          query_params[:name] = model_name if model_name
-          query_params[:model_type] = model_type if model_type
+          query_params = params.request_parameters
           uri.query = URI.encode_www_form(query_params) unless query_params.empty?
 
           headers = {
@@ -86,14 +73,18 @@ module Mindee
             'User-Agent' => @settings.user_agent,
           }
           req = Net::HTTP::Get.new(uri, headers)
-          req['Transfer-Encoding'] = 'chunked'
 
-          Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @settings.request_timeout) do |http|
-            return http.request(req)
+          response = Net::HTTP.start(uri.hostname, uri.port,
+                                     use_ssl: true,
+                                     open_timeout: @settings.request_timeout,
+                                     read_timeout: @settings.request_timeout) do |http|
+            http.request(req)
           end
-          raise Mindee::Error::MindeeError, 'Could not resolve server response.'
+          params.response_class.new(process_response(response))
         end
 
+        private
+
         # @param resource [String] Resource to check.
         # @return [Boolean]
         def uri?(resource)
@@ -155,9 +146,11 @@ module Mindee
             'User-Agent' => @settings.user_agent,
           }
           req = Net::HTTP::Get.new(uri, headers)
-          req['Transfer-Encoding'] = 'chunked'
 
-          Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @settings.request_timeout) do |http|
+          Net::HTTP.start(uri.hostname, uri.port,
+                          use_ssl: true,
+                          open_timeout: @settings.request_timeout,
+                          read_timeout: @settings.request_timeout) do |http|
             return http.request(req)
           end
           raise Mindee::Error::MindeeError, 'Could not resolve server response.'
@@ -191,7 +184,7 @@ module Mindee
         end
 
         # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
-        # @param params [Input::BaseParameters] Inference options.
+        # @param params [ClientOptions::BaseProductParameters] Inference options.
         # @return [Net::HTTPResponse, nil]
         def enqueue(input_source, params)
           uri = URI("#{@settings.base_url}/v2/products/#{params.slug}/enqueue")
@@ -218,7 +211,10 @@ module Mindee
           req.set_form(form_data, 'multipart/form-data')
           req['Transfer-Encoding'] = 'chunked'
 
-          Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @settings.request_timeout) do |http|
+          Net::HTTP.start(uri.hostname, uri.port,
+                          use_ssl: true,
+                          open_timeout: @settings.request_timeout,
+                          read_timeout: @settings.request_timeout) do |http|
             return http.request(req)
           end
           raise Mindee::Error::MindeeError, 'Could not resolve server response.'

data/lib/mindee/v2/parsing/search/base_search_response.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V2
+    module Parsing
+      module Search
+        # Base class for search responses.
+        class BaseSearchResponse < CommonResponse
+          # Pagination metadata.
+          # @return [Mindee::V2::Parsing::Search::PaginationMetadata]
+          attr_reader :pagination
+
+          # @param http_response [Hash] The parsed JSON payload from the API.
+          def initialize(http_response)
+            super
+
+            @pagination = PaginationMetadata.new(http_response['pagination'])
+          end
+
+          # Lines composing the response-specific body (header + items).
+          # @return [Array<String>]
+          def body_lines
+            raise NotImplementedError, 'body_lines must be implemented in subclasses'
+          end
+
+          # Pagination metadata (Obsolete).
+          # @deprecated Use {#pagination} instead.
+          # @return [Mindee::V2::Parsing::Search::PaginationMetadata]
+          def pagination_metadata
+            pagination
+          end
+
+          # String representation of the search response.
+          # @return [String]
+          def to_s
+            lines = body_lines
+            lines.push('Pagination Metadata')
+            lines.push('###################')
+            lines.push(@pagination.to_s)
+
+            lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/v2/parsing/search/model_webhook.rb

@@ -4,7 +4,7 @@ module Mindee
   module V2
     module Parsing
       module Search
-        # Individual webhook information.
+        # Information about a model's webhook.
         class ModelWebhook
           # @return [String] ID of the webhook.
           attr_reader :id
@@ -15,14 +15,14 @@ module Mindee
           # @return [String] URL of the webhook.
           attr_reader :url
 
-          # @param payload [Hash] The parsed JSON payload mapping to the search model.
+          # @param payload [Hash] The parsed JSON payload mapping to the webhook.
           def initialize(payload)
             @id = payload['id']
             @name = payload['name']
             @url = payload['url']
           end
 
-          # String representation of the model.
+          # String representation of the webhook.
           # @return [String]
           def to_s
             [

data/lib/mindee/v2/parsing/search/pagination_metadata.rb

@@ -4,7 +4,7 @@ module Mindee
   module V2
     module Parsing
       module Search
-        # Pagination Metadata data associated with model search.
+        # Pagination metadata associated with searches.
         class PaginationMetadata
           # @return [Integer] Number of items per page.
           attr_reader :per_page

data/lib/mindee/v2/parsing/search/search_models.rb

@@ -4,8 +4,9 @@ module Mindee
   module V2
     module Parsing
       module Search
-        # Array of search models.
+        # List of search models.
         class SearchModels < Array
+          # @param prediction [Array<Hash>] The parsed JSON payload mapping to the search models.
           def initialize(prediction)
             super(prediction.map { |entry| SearchModel.new(entry) })
           end

data/lib/mindee/v2/parsing/search/search_rag_document.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Mindee
+  module V2
+    module Parsing
+      module Search
+        # Individual RAG document information.
+        class SearchRAGDocument
+          # @return [String] Unique identifier of the RAG document.
+          attr_reader :id
+
+          # @return [String] Model identifier linked to the RAG document.
+          attr_reader :model_id
+
+          # @return [String] Original filename of the uploaded document.
+          attr_reader :filename
+
+          # @return [Time] Date and time of the document creation.
+          attr_reader :created_at
+
+          # @return [Integer] Number of times this document was used in an inference.
+          attr_reader :total_matches
+
+          # @return [Time, nil] Date and time of the latest matching inference, if any.
+          attr_reader :last_match_at
+
+          # @return [String] Current status of the RAG document.
+          attr_reader :status
+
+          # @param server_response [Hash] The parsed JSON payload mapping to the RAG document.
+          def initialize(server_response)
+            @id = server_response['id']
+            @model_id = server_response['model_id']
+            @filename = server_response['filename']
+            @created_at = Time.iso8601(server_response['created_at'])
+            @total_matches = server_response['total_matches']
+            @last_match_at = (Time.iso8601(server_response['last_match_at']) if server_response['last_match_at'])
+            @status = server_response['status']
+          end
+
+          # String representation of the RAG document.
+          # @return [String]
+          def to_s
+            [
+              ":ID: #{@id}",
+              ":Model ID: #{@model_id}",
+              ":Filename: #{@filename}",
+              ":Created At: #{@created_at}",
+              ":Total Matches: #{@total_matches}",
+              ":Last Match At: #{@last_match_at}",
+              ":Status: #{@status}",
+            ].join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/v2/parsing/search/search_rag_documents.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'search_rag_document'
+
+module Mindee
+  module V2
+    module Parsing
+      module Search
+        # List of RAG documents.
+        class SearchRAGDocuments < Array
+          # @param raw_response [Array<Hash>] The parsed JSON payload mapping to the RAG documents.
+          def initialize(raw_response)
+            super(raw_response.map { |entry| SearchRAGDocument.new(entry) })
+          end
+
+          # Default string representation.
+          # @return [String]
+          def to_s
+            return "\n" if empty?
+
+            lines = flat_map do |rag_document|
+              [
+                "* :ID: #{rag_document.id}",
+                "  :Model ID: #{rag_document.model_id}",
+                "  :Filename: #{rag_document.filename}",
+                "  :Created At: #{rag_document.created_at}",
+                "  :Total Matches: #{rag_document.total_matches}",
+                "  :Last Match At: #{rag_document.last_match_at}",
+                "  :Status: #{rag_document.status}",
+              ]
+            end
+
+            "#{lines.join("\n")}\n"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/v2/parsing/search/search_response.rb

@@ -5,35 +5,8 @@ module Mindee
     module Parsing
       module Search
         # Models search response.
-        class SearchResponse < CommonResponse
-          # @return [Search::SearchModels] Parsed search payload.
-          attr_reader :models
-          # @return [Search::PaginationMetadata] Pagination metadata.
-          attr_reader :pagination
-          # @return [Search::PaginationMetadata] Pagination metadata.
-          attr_reader :pagination_metadata
-
-          def initialize(server_response)
-            super
-
-            @models = SearchModels.new(server_response['models'])
-            @pagination = PaginationMetadata.new(server_response['pagination'])
-            @pagination_metadata = @pagination
-          end
-
-          # String representation.
-          # @return [String]
-          def to_s
-            [
-              'Models',
-              '######',
-              @models.to_s,
-              'Pagination Metadata',
-              '###################',
-              @pagination.to_s,
-              '',
-            ].join("\n")
-          end
+        # @deprecated Use {Mindee::V2::Search::Models::ModelSearchResponse} instead.
+        class SearchResponse < Mindee::V2::Search::Models::ModelSearchResponse
         end
       end
     end

data/lib/mindee/v2/parsing/search.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require_relative 'search/pagination_metadata'
+require_relative 'search/model_webhook'
 require_relative 'search/search_model'
 require_relative 'search/search_models'
+require_relative 'search/search_rag_document'
+require_relative 'search/search_rag_documents'
+require_relative 'search/base_search_response'
+require_relative '../search/models/model_search_response'
 require_relative 'search/search_response'
-require_relative 'search/model_webhook'

data/lib/mindee/v2/product/base_product.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../parsing/base_response'
-require_relative '../../input/base_parameters'
+require_relative '../client_options/base_product_parameters'
 
 module Mindee
   module V2
@@ -11,7 +11,7 @@ module Mindee
         # @return [String] The slug of the endpoint used for this response
         @slug = ''
         # @return [Class<BaseParameters>] The class of the parameters used for this response
-        @params_type = Mindee::Input::BaseParameters
+        @params_type = Mindee::V2::ClientOptions::BaseProductParameters
         # @return [Class<BaseResponse>] The class of the response used for this product
         @response_type = Mindee::V2::Parsing::BaseResponse
 

data/lib/mindee/v2/product/classification/classification_classifier.rb

@@ -13,11 +13,10 @@ module Mindee
           # @param server_response [Hash] Hash representation of the JSON returned by the service.
           def initialize(server_response)
             @document_type = server_response['document_type']
-            # rubocop:disable Style/GuardClause
+            # rubocop:disable-next Style/GuardClause
             unless server_response['extraction_response'].nil?
               @extraction_response = V2::Product::Extraction::ExtractionResponse.new(server_response['extraction_response'])
             end
-            # rubocop:enable Style/GuardClause
           end
 
           # @return [String] String representation.

data/lib/mindee/v2/product/classification/params/classification_parameters.rb

@@ -7,7 +7,7 @@ module Mindee
         # Classification parameters.
         module Params
           # Parameters accepted by the classification utility v2 endpoint.
-          class ClassificationParameters < Mindee::Input::BaseParameters
+          class ClassificationParameters < Mindee::V2::ClientOptions::BaseProductParameters
             # @return [String] Slug for the endpoint.
             def self.slug
               'classification'

data/lib/mindee/v2/product/crop/crop_item.rb

@@ -16,11 +16,10 @@ module Mindee
           def initialize(server_response)
             @object_type = server_response['object_type']
             @location = Mindee::V2::Parsing::Field::FieldLocation.new(server_response['location'])
-            # rubocop:disable Style/GuardClause
+            # rubocop:disable-next Style/GuardClause
             unless server_response['extraction_response'].nil?
               @extraction_response = V2::Product::Extraction::ExtractionResponse.new(server_response['extraction_response'])
             end
-            # rubocop:enable Style/GuardClause
           end
 
           # String representation.

data/lib/mindee/v2/product/crop/params/crop_parameters.rb

@@ -7,7 +7,7 @@ module Mindee
         # Crop parameters.
         module Params
           # Parameters accepted by the crop utility v2 endpoint.
-          class CropParameters < Mindee::Input::BaseParameters
+          class CropParameters < Mindee::V2::ClientOptions::BaseProductParameters
             # @return [String] Slug for the endpoint.
             def self.slug
               'crop'

data/lib/mindee/v2/product/extraction/params/extraction_parameters.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../../../../input/base_parameters'
+require_relative '../../../client_options/base_product_parameters'
 require_relative 'data_schema'
 
 module Mindee
@@ -9,7 +9,7 @@ module Mindee
       module Extraction
         module Params
           # Parameters accepted by the extraction v2 endpoint.
-          class ExtractionParameters < Mindee::Input::BaseParameters
+          class ExtractionParameters < Mindee::V2::ClientOptions::BaseProductParameters
             # @return [Boolean, nil] Enhance extraction accuracy with Retrieval-Augmented Generation.
             attr_reader :rag