mindee-lite 5.4.0 → 5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5847f9a9f62853290ae96d8a311c66af32cbf5e1f74da6f0e7d0b455a76ae931
-  data.tar.gz: 5fbbd21a967ff60ddc059fa9ed9d5f3fd7422890e3f3675d38347f82a5463da8
+  metadata.gz: 2a8d5975bde93678d55dacd3aca14239e736c643778346d6b3c350576593e086
+  data.tar.gz: ceadc33d7e44f574d9657124ba17683c996af4f0433c94ccba165908899fe422
 SHA512:
-  metadata.gz: a238ed199069908c8fe5488de1af41436650f77288685297f5da4d5b1cec5c617dfa76c843b6b02efd63fa617b8dc7f80872593d63f1f7b854fce886aa6bd327
-  data.tar.gz: c2845fc9b049a1b123b15678e4effdfb55f382650cb9eecc90244ec553a78679dd1523226e8826a5e3abfbcc95bff85c790aeabcde10d36696cffa977594e3c4
+  metadata.gz: 566da7a6fff0b975ffbdc72901e254bf70f487fbac1f0c67b6e7095a2c510cbdf9ea2314788263c61be703e4a054f54887264a99218a5ca640c1396130347015
+  data.tar.gz: c1fbfff08eca29a3d0e2d64d00f8b46fd6b85a6fa50b809dc9ba89e42ba999985b00b244a4ff10d2db34e66dbce2ab714afd811b8fa06b0c40c6f8b999beae99

data/.git-hooks/pre_commit/gitleaks.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Overcommit
+  module Hook
+    module PreCommit
+      # Local script to run gitleaks
+      class Gitleaks < Base
+        # Runs the command.
+        def run
+          result = execute(['gitleaks', 'git', '--staged', '-v', '.'])
+
+          return :pass if result.success?
+
+          [:fail, result.stdout + result.stderr]
+        end
+      end
+    end
+  end
+end

data/.overcommit.yml

@@ -0,0 +1,46 @@
+PreCommit:
+  MergeConflicts:
+    enabled: true
+
+  YamlSyntax:
+    enabled: true
+
+  TrailingWhitespace:
+    enabled: true
+
+  FileSize:
+    enabled: true
+    byte_limit: 1048576
+
+  RuboCop:
+    enabled: true
+    required_executable: 'bundle'
+    command: ['bundle', 'exec', 'rubocop', '--force-exclusion', '--no-server']
+
+  CustomScript:
+    enabled: true
+    description: 'Run Steep type checking'
+    required_executable: 'bundle'
+    command: ['bundle', 'exec', 'steep', 'check']
+
+  Gitleaks:
+    enabled: true
+    required_executable: 'gitleaks'
+  CommitMsg:
+    enabled: false
+    CapitalizedSubject:
+      enabled: false
+    TextWidth:
+      enabled: false
+    TrailingPeriod:
+      enabled: false
+    SingleLineSubject:
+      enabled: false
+    EmptyMessage:
+      enabled: false
+
+PrePush:
+  BundleAudit:
+    enabled: true
+    required_executable: 'bundle'
+    command: ['sh', '-c', 'bundle exec bundle-audit check']

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Mindee Ruby API Library Changelog
 
+## v5.5.0 - 2026-09-30
+### Changes
+* :sparkles: add support for RAG search
+* :wrench: switching over from pre-commit to ruby-only solution
+### Fixes
+* :bug: fix V2 hangs on GET
+
+
 ## v5.4.0 - 2026-07-21
 ### Changes
 * :sparkles: add field confidence comparators

data/CONTRIBUTING.md

@@ -68,6 +68,134 @@ Please follow these steps to have your contribution considered by the maintainer
 
 While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
 
+## Development Setup
+
+### 1. Ruby
+
+[`rbenv`](https://github.com/rbenv/rbenv) is the recommended way to manage Ruby versions:
+
+```shell
+# Finalize the rbenv install (should work with both bash & zsh)
+~/.rbenv/bin/rbenv init
+# And then run
+eval "$(~/.rbenv/bin/rbenv init - bash)"
+```
+
+### 2. Clone the repository
+
+Test data lives in a submodule, so make sure to clone recursively:
+
+```shell
+git clone --recurse-submodules git@github.com:mindee/mindee-api-ruby.git ~/work/mindee/mindee-api-ruby
+cd ~/work/mindee/mindee-api-ruby
+```
+
+If you already cloned without `--recurse-submodules`, run `git submodule update --init --recursive`.
+
+### 3. Install dependencies
+
+On Debian/Ubuntu:
+
+```shell
+sudo apt install zlib1g-dev libssl-dev libreadline-dev libedit-dev libyaml-dev imagemagick
+```
+
+`imagemagick` is required at runtime by `mini_magick`, the rest are needed to build Ruby itself.
+
+```shell
+# Ruby 3.3.0 is the minimum version supported by the SDK
+rbenv install 3.3.0
+rbenv global 3.3.0
+```
+
+### 4. Install code dependencies
+
+```shell
+bundle config set --local path vendor
+bundle install
+```
+
+### 5. Validate the install works by running unit tests
+
+```shell
+bundle exec rake spec
+```
+
+## Local Quality Checks
+
+We use [`overcommit`](https://github.com/sds/overcommit) to run quality and security checks before
+changes are committed and pushed. It is a development dependency of the gem, so `bundle install`
+already installed it. The hooks are configured in [`.overcommit.yml`](.overcommit.yml), and
+repository-local custom hooks live in [`.git-hooks`](.git-hooks).
+
+The same checks run in CI, see
+[`.github/workflows/_static-analysis.yml`](.github/workflows/_static-analysis.yml).
+
+### Install `gitleaks`
+
+The `Gitleaks` pre-commit hook shells out to the
+[`gitleaks`](https://github.com/gitleaks/gitleaks) binary, which is not a gem and must be installed
+separately:
+
+```shell
+brew install gitleaks
+```
+
+Otherwise, grab a binary from the
+[releases page](https://github.com/gitleaks/gitleaks/releases) and put it on your `PATH`.
+
+### Install the hooks
+
+Run this once, after cloning:
+
+```shell
+bundle exec overcommit --install
+bundle exec overcommit --sign
+bundle exec overcommit --sign pre-commit
+```
+
+`--install` writes the git hook stubs into `.git/hooks`, and the `--sign` calls tell overcommit you
+trust the current contents of `.overcommit.yml` and of the custom hooks in `.git-hooks`.
+
+### What runs, and when
+
+* **pre-commit:** merge conflict markers, YAML syntax, trailing whitespace, file size, `rubocop`,
+  `steep check` (type checking) and `gitleaks` (secret scanning).
+* **pre-push:** `bundle-audit` (dependency vulnerability check).
+
+### Run the hooks manually
+
+```shell
+bundle exec overcommit --list-hooks         # show which hooks are enabled
+bundle exec overcommit --run                # run the pre-commit hooks on all tracked files
+bundle exec overcommit --run pre_push       # run the pre-push hooks
+bundle exec overcommit --diff main          # run the pre-commit hooks on the diff against main
+```
+
+### Skipping hooks
+
+Skip one or more hooks for a single run, by name:
+
+```shell
+SKIP=Gitleaks,Steep git commit
+```
+
+To bypass overcommit entirely (please use sparingly, CI runs the same checks):
+
+```shell
+OVERCOMMIT_DISABLE=1 git commit
+```
+
+### Troubleshooting
+
+If overcommit refuses to run and warns that the configuration or the hooks have changed, review the
+diff and then re-sign:
+
+```shell
+bundle exec overcommit --sign
+bundle exec overcommit --sign pre-commit
+```
+
 ## Styleguides
 
 ### Git Commit Messages

data/bin/mindee.rb

@@ -9,7 +9,10 @@ require_relative 'v2/parser'
 def root_help
   help = "Usage: mindee command [options]\n\nAvailable commands:\n"
   help += "  #{'v1'.ljust(50)}Use Version 1 of the Mindee API\n"
-  help += "  #{'search-models'.ljust(50)}Search for available models for this API key\n"
+
+  MindeeCLI::V2SearchCommands::V2_SEARCH_COMMANDS.each do |search_command, search_values|
+    help += "  #{search_command.ljust(50)}#{search_values[:description]}\n"
+  end
 
   V2_PRODUCTS.each do |product_key, product_values|
     help += "  #{product_key.ljust(50)}#{product_values[:description]}\n"

data/bin/v2/parser.rb

@@ -2,11 +2,14 @@
 
 require 'mindee'
 require_relative 'products'
+require_relative 'search_commands'
 
 module MindeeCLI
   # Mindee Command Line Interface
   # V2 CLI class.
   class V2Parser
+    include V2SearchCommands
+
     # @return [Array<String>]
     attr_reader :arguments
 
@@ -17,7 +20,10 @@ module MindeeCLI
     attr_reader :product_parser
 
     # @return [Parser]
-    attr_reader :search_parser
+    attr_reader :search_models_parser
+
+    # @return [Parser]
+    attr_reader :search_rag_docs_parser
 
     def initialize(arguments, command_prefix: 'mindee v2')
       @arguments = arguments
@@ -26,26 +32,18 @@ module MindeeCLI
         opts.banner = "Usage: #{@command_prefix} command [options]"
       end
       @product_parser = init_product_parser
-      @search_parser = init_search_parser
+      @search_models_parser = init_search_models_parser
+      @search_rag_docs_parser = init_search_rag_docs_parser
     end
 
     # Summarize and print the result of the command.
     # @param command [String]
     def print_result(command)
-      if command == 'search-models'
-        @search_parser.parse!(@arguments)
-        result = search(@options)
-        summarized_result = output_format == :full ? result.to_s : result.models.to_s
-      else
-        @product_parser[command].parse!(@arguments)
-        @options[:file_path] = @arguments.shift
-        if @options[:file_path].nil?
-          warn 'file missing'
-          abort(@product_parser[command].help)
-        end
-        result = send(command, @options)
-        summarized_result = output_format == :full ? result.inference.to_s : result.inference.result.to_s
-      end
+      result, summarized_result = if V2_SEARCH_COMMANDS.key?(command)
+                                    run_search(command)
+                                  else
+                                    run_product(command)
+                                  end
 
       if output_format == :raw
         puts JSON.pretty_generate(raw_payload(result.raw_http))
@@ -63,22 +61,41 @@ module MindeeCLI
       validate_command!(command)
       print_result(command)
     rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
-      if command == 'search-models'
-        abort("#{e.message}\n\n#{@search_parser.help}")
-      else
-        abort("#{e.message}\n\n#{@product_parser[command].help}")
-      end
+      abort("#{e.message}\n\n#{command_parser(command).help}")
     rescue Mindee::Error::MindeeError => e
       abort(format_cli_error(e))
     end
 
     private
 
+    # Parse the arguments and run the given product command.
+    # @param command [String]
+    # @return [Array(Mindee::V2::Parsing::BaseResponse, String)] Response and its summary.
+    def run_product(command)
+      @product_parser[command].parse!(@arguments)
+      @options[:file_path] = @arguments.shift
+      if @options[:file_path].nil?
+        warn 'file missing'
+        abort(@product_parser[command].help)
+      end
+      result = send(command, @options)
+      summarized_result = output_format == :full ? result.inference.to_s : result.inference.result.to_s
+      [result, summarized_result]
+    end
+
+    # @param command [String]
+    # @return [OptionParser]
+    def command_parser(command)
+      V2_SEARCH_COMMANDS.key?(command) ? search_parser_for(command) : @product_parser[command]
+    end
+
     def validate_command!(command)
-      return if V2_PRODUCTS.include?(command) || command == 'search-models'
+      return if V2_PRODUCTS.include?(command) || V2_SEARCH_COMMANDS.key?(command)
 
       error_msg = "#{@options_parser.help}\nAvailable commands:\n"
-      error_msg += "  #{'search-models'.ljust(50)}Search for available models for this API key\n"
+      V2_SEARCH_COMMANDS.each do |search_command, search_values|
+        error_msg += "  #{search_command.ljust(50)}#{search_values[:description]}\n"
+      end
 
       V2_PRODUCTS.each do |product_key, product_values|
         error_msg += "  #{product_key.to_s.ljust(50)}#{product_values[:description]}\n"
@@ -98,21 +115,6 @@ module MindeeCLI
       end
     end
 
-    def init_search_parser
-      OptionParser.new do |options_parser|
-        options_parser.banner = "Usage: #{@command_prefix} search-models [options]"
-        init_common_options(options_parser)
-        options_parser.on('-n [NAME]', '--name [NAME]',
-                          'Search for partial matches in model name. Note: case insensitive') do |v|
-          @options[:model_name] = v
-        end
-        options_parser.on('-t [NAME]', '--type [NAME]',
-                          'Search for EXACT matches in model type. Note: case sensitive') do |v|
-          @options[:model_type] = v
-        end
-      end
-    end
-
     def setup_specific_options(options_parser, doc_value)
       options_parser.on('-r', '--rag', 'Enable RAG') { @options[:rag] = true } if doc_value.key?(:rag)
       if doc_value.key?(:raw_text)
@@ -218,13 +220,6 @@ module MindeeCLI
       )
     end
 
-    # @param options [Hash]
-    # @return [Mindee::V2::Parsing::Search::SearchResponse]
-    def search(options)
-      mindee_client = Mindee::V2::Client.new(api_key: options[:api_key])
-      mindee_client.search_models(options[:model_name], options[:model_type])
-    end
-
     # @param options [Hash]
     # @return [Mindee::Input::InputSource]
     def setup_input_source(options)

data/bin/v2/search_commands.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'mindee'
+require_relative 'products'
+
+module MindeeCLI
+  # Search-related commands for the V2 CLI.
+  module V2SearchCommands
+    # NOTE: keep command names as string instead of symbols due to kebab-case.
+    V2_SEARCH_COMMANDS = {
+      'search-models' => {
+        description: 'Search available models.',
+        parser: :search_models_parser,
+        runner: :search_models,
+        summary: :models,
+      },
+      'search-rag-docs' => {
+        description: 'Search available RAG documents for a given model.',
+        parser: :search_rag_docs_parser,
+        runner: :search_rag_documents,
+        summary: :rag_documents,
+      },
+    }.freeze
+
+    private
+
+    # Parse the arguments and run the given search command.
+    # @param command [String]
+    # @return [Array(Mindee::V2::Parsing::Search::BaseSearchResponse, String)] Response and its summary.
+    def run_search(command)
+      search_command = V2_SEARCH_COMMANDS[command]
+      search_parser_for(command).parse!(@arguments)
+      result = __send__(search_command[:runner], @options)
+      summarized_result = output_format == :full ? result.to_s : result.public_send(search_command[:summary]).to_s
+      [result, summarized_result]
+    end
+
+    # @param command [String]
+    # @return [OptionParser]
+    def search_parser_for(command)
+      __send__(V2_SEARCH_COMMANDS[command][:parser])
+    end
+
+    # @return [OptionParser]
+    def init_search_models_parser
+      OptionParser.new do |options_parser|
+        options_parser.banner = "Usage: #{@command_prefix} search-models [options]"
+        init_common_options(options_parser)
+        options_parser.on('-n [NAME]', '--name [NAME]',
+                          'Filter by model name partial match (case insensitive).') do |v|
+          @options[:model_name] = v
+        end
+        options_parser.on('-m [MODEL_TYPE]', '--model-type [MODEL_TYPE]',
+                          'Filter by exact model type (case sensitive).',
+                          "Available options: #{V2_PRODUCTS.keys.join(', ')}") do |v|
+          @options[:model_type] = v
+        end
+      end
+    end
+
+    # @return [OptionParser]
+    def init_search_rag_docs_parser
+      OptionParser.new do |options_parser|
+        options_parser.banner = "Usage: #{@command_prefix} search-rag-docs [options]"
+        init_common_options(options_parser)
+        options_parser.on('-m MODEL_ID', '--model-id MODEL_ID', 'Filter by model ID') do |v|
+          @options[:model_id] = v
+        end
+        options_parser.on('-f [FILENAME]', '--filename [FILENAME]',
+                          'Filter by file name partial match (case insensitive).') do |v|
+          @options[:filename] = v
+        end
+      end
+    end
+
+    # @param options [Hash]
+    # @return [Mindee::V2::Search::Models::ModelSearchResponse]
+    def search_models(options)
+      mindee_client = Mindee::V2::Client.new(api_key: options[:api_key])
+      mindee_client.search(
+        Mindee::V2::Search::Models::ModelSearchParameters.new(
+          name: options[:model_name],
+          model_type: options[:model_type]
+        )
+      )
+    end
+
+    # @param options [Hash]
+    # @return [Mindee::V2::Search::RAGDocuments::RAGDocumentSearchResponse]
+    def search_rag_documents(options)
+      mindee_client = Mindee::V2::Client.new(api_key: options[:api_key])
+      mindee_client.search(
+        Mindee::V2::Search::RAGDocuments::RAGDocumentSearchParameters.new(
+          model_id: options[:model_id],
+          filename: options[:filename]
+        )
+      )
+    end
+  end
+end

data/lib/mindee/v1/client.rb

@@ -250,7 +250,7 @@ module Mindee
       # @param endpoint [Mindee::V1::HTTP::Endpoint] Endpoint of the API.
       # @param cancellation_token [Mindee::HTTP::CancellationToken, nil] Token for cancellation.
       # @return [Mindee::V1::Parsing::Common::ApiResponse]
-      # rubocop:disable Metrics/PerceivedComplexity
+      # rubocop:disable-next Metrics/PerceivedComplexity
       def enqueue_and_parse(
         input_source,
         product_class,
@@ -293,7 +293,6 @@ module Mindee
 
         queue_res
       end
-      # rubocop:enable Metrics/PerceivedComplexity
 
       # rubocop:enable Metrics/CyclomaticComplexity
       # Sends a document to a workflow.

data/lib/mindee/v2/client.rb

@@ -37,7 +37,7 @@ module Mindee
       # @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, Input::BaseParameters] Parameters for the inference.
+      # @param params [Hash, ClientOptions::BaseProductParameters] Parameters for the inference.
       # @return [Mindee::V2::Parsing::JobResponse]
       def enqueue(
         product,
@@ -48,7 +48,7 @@ module Mindee
         normalized_params.validate_async_params
         logger.debug("Enqueueing document to model '#{normalized_params.model_id}'.")
 
-        @mindee_api.req_post_enqueue(input_source, normalized_params)
+        @mindee_api.req_post_product_enqueue(input_source, normalized_params)
       end
 
       # Enqueues to an asynchronous endpoint and automatically polls for a response.
@@ -56,11 +56,11 @@ module Mindee
       # @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, Input::BaseParameters] Parameters for the inference.
+      # @param params [Hash, ClientOptions::BaseProductParameters] Parameters for the inference.
       # @param polling_options [Hash, PollingOptions, nil] Parameters for polling.
       # @param cancellation_token [Mindee::HTTP::CancellationToken, nil] Token for cancellation.
       # @return [Parsing::BaseResponse]
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def enqueue_and_get_result(
         product,
         input_source,
@@ -117,14 +117,21 @@ module Mindee
         raise Mindee::Error::MindeeError,
               "Asynchronous parsing request timed out after #{sec_count} seconds"
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
-      # Searches for a list of available models for the given API key.
-      # @param model_name [String]
-      # @param model_type [String]
-      # @return [Mindee::V2::Parsing::Search::SearchResponse]
+      # Search for resources matching the given criteria.
+      # @param params [ClientOptions::BaseSearchParameters] Search parameters.
+      # @return [Mindee::V2::Parsing::Search::BaseSearchResponse] A search response containing the matching resources.
+      def search(params)
+        @mindee_api.req_get_search(params)
+      end
+
+      # Returns a list of models matching a criteria for the given API key.
+      # @deprecated Use {#search} instead.
+      # @param model_name [String, nil] Name filter.
+      # @param model_type [String, nil] Model type filter.
+      # @return [Mindee::V2::Search::Models::ModelSearchResponse]
       def search_models(model_name, model_type)
-        @mindee_api.search_models(model_name, model_type)
+        search(Search::Models::ModelSearchParameters.new(name: model_name, model_type: model_type))
       end
 
       private
@@ -136,7 +143,7 @@ module Mindee
       def normalize_parameters(param_class, params, polling_options: nil)
         if params.is_a?(Hash)
           params[:polling_options] = polling_options if polling_options
-        elsif params.is_a?(Mindee::Input::BaseParameters) && !polling_options.nil?
+        elsif params.is_a?(Mindee::V2::ClientOptions::BaseProductParameters) && !polling_options.nil?
           params.polling_options = polling_options
         end
         return param_class.from_hash(params: params) if params.is_a?(Hash)