mindee 5.4.0 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cda258819aabaa34266728d26130b0137ad8d86d770c9d395245e373b1bc96e4
-  data.tar.gz: 5fbbd21a967ff60ddc059fa9ed9d5f3fd7422890e3f3675d38347f82a5463da8
+  metadata.gz: f836bb72cfae4c43ad226be7bcbfc3e39606b4df6dae6ef9fece37ec0a957d4c
+  data.tar.gz: 155f5b82fe3e3fcecb17400040ad3543304b6dc6dbd94a9870ebc6b8b0dcf3bb
 SHA512:
-  metadata.gz: 956efea9a0245e734c9c1b313ad0e1a74f9c5245df05f3bb1e17ab2a3b4a5031b9d0fc21110f0db33dd08d85d0427cfda1c6f265b05177e1900b761274398fb0
-  data.tar.gz: c2845fc9b049a1b123b15678e4effdfb55f382650cb9eecc90244ec553a78679dd1523226e8826a5e3abfbcc95bff85c790aeabcde10d36696cffa977594e3c4
+  metadata.gz: 87625c60d12034c9914e18acf6cf93e226cce1a3fac810849fb73d009964e825d933e9ea370e54c89a2d43e2fb5457c50dad7aab2183ad6ccc2645806749554f
+  data.tar.gz: c5a21cefe733fadb998c5ed051754f1e8193ea9682c0cf52fa32a8c7345cd45d89e27f1b02a9b062a1713197a6f2735ca7cfa462f3cd5d131a2b25a1de610939

data/.betterleaks.toml

@@ -0,0 +1,15 @@
+[extend]
+useDefault = true
+
+[[allowlists]]
+description = "RBS type signatures are not secrets"
+condition = "AND"
+regexTarget = "match"
+paths = ['''^sig/.*\.rbs$''']
+regexes = ['''password:\s*String\??''']
+
+[[allowlists]]
+description = "Dummy HMAC secret used in LocalResponse unit tests"
+condition = "AND"
+paths = ['''^spec/.*\.rb$''']
+regexes = ['''ogNjY44MhvKPGTtVsI8zG82JqWQa68woYQH''']

data/.editorconfig

@@ -12,7 +12,7 @@ trim_trailing_whitespace = false
 indent_style = space
 indent_size = 2
 
-[*.{yml,yaml,json}]
+[*.{yml,yaml,json,toml}]
 indent_style = space
 indent_size = 2
 

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Mindee Ruby API Library Changelog
 
+## v5.6.0 - 2026-11-04
+### Changes
+* coffin: remove dead v1 products and workflow methods
+* :sparkles: add get by URL methods
+
+
+## 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,94 @@ 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 [`prek`](https://prek.j178.dev/) to run quality and security checks before changes are committed and pushed.
+
+The same checks run in CI, see
+[`.github/workflows/_static-analysis.yml`](.github/workflows/_static-analysis.yml).
+
+### Install the hooks
+
+https://prek.j178.dev/installation/
+
+Then install the hooks:
+
+```shell
+prek install
+```
+
+Now, when you run `git commit`, `prek` will automatically run the quality and security checks.
+
+### Run the hooks manually
+
+If you need to run the hooks manually, use the following command:
+
+```shell
+prek run --all-files
+```
+
+### Skipping hooks
+
+Skip one or more hooks for a single run, by ID:
+
+```shell
+PREK_SKIP=rubocop
+```
+
 ## 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/v1/products.rb

@@ -7,12 +7,6 @@ V1_PRODUCTS = {
     sync: true,
     async: true,
   },
-  'barcode-reader' => {
-    description: 'Barcode Reader',
-    doc_class: Mindee::V1::Product::BarcodeReader::BarcodeReaderV1,
-    sync: true,
-    async: false,
-  },
   'cropper' => {
     description: 'Cropper',
     doc_class: Mindee::V1::Product::Cropper::CropperV1,

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

@@ -54,39 +54,6 @@ module Mindee
       end
     end
 
-    # Class for configuration options in workflow executions.
-    #
-    # @!attribute document_alias [String, nil] Alias to give to the document.
-    # @!attribute priority [Symbol, nil] Priority to give to the document.
-    # @!attribute full_text [bool] Whether to include the full OCR text response in compatible APIs.
-    #   This performs a full OCR operation on the server and may increase response time.
-    # @!attribute public_url [String, nil] A unique, encrypted URL for accessing the document validation interface
-    # without requiring authentication.
-    # @!attribute rag [bool, nil] Whether to enable Retrieval-Augmented Generation.
-    # @!attribute page_options [PageOptions, Hash, nil] Page cutting/merge options:
-    #   * `:page_indexes` Zero-based list of page indexes.
-    #   * `:operation` 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.
-    #   * `: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, :close_file
-
-      def initialize(params: {})
-        params = params.transform_keys(&:to_sym)
-        @document_alias = params.fetch(:document_alias, nil)
-        @priority = params.fetch(:priority, nil)
-        @full_text = params.fetch(:full_text, false)
-        @public_url = params.fetch(:public_url, nil)
-        @rag = params.fetch(:rag, nil)
-        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
-
     # Mindee API Client.
     # See: https://developers.mindee.com/docs
     class Client
@@ -219,7 +186,6 @@ module Mindee
         Mindee::V1::Parsing::Common::ApiResponse.new(product_class, prediction, raw_http)
       end
 
-      # rubocop:disable Metrics/CyclomaticComplexity
       # Enqueue a document for async parsing and automatically try to retrieve it
       #
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
@@ -250,7 +216,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, Metrics/CyclomaticComplexity
       def enqueue_and_parse(
         input_source,
         product_class,
@@ -293,46 +259,6 @@ module Mindee
 
         queue_res
       end
-      # rubocop:enable Metrics/PerceivedComplexity
-
-      # rubocop:enable Metrics/CyclomaticComplexity
-      # Sends a document to a workflow.
-      #
-      # Accepts options either as a Hash or as a WorkflowOptions struct.
-      #
-      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
-      # @param workflow_id [String]
-      # @param options [Hash, WorkflowOptions] Options to configure workflow behavior.  Possible keys:
-      #   * `document_alias` [String, nil] Alias to give to the document.
-      #   * `priority` [Symbol, nil] Priority to give to the document.
-      #   * `full_text` [bool] Whether to include the full OCR text response in compatible APIs.
-      #   * `rag` [bool, nil] Whether to enable Retrieval-Augmented Generation.
-      #
-      #   * `public_url` [String, nil] A unique, encrypted URL for accessing the document validation interface without
-      # requiring authentication.
-      #   * `page_options` [Hash, nil] Page cutting/merge options:
-      #     * `:page_indexes` Zero-based list of page indexes.
-      #       * `:operation` Operation to apply on the document, given the `page_indexes specified:
-      #          * `: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 document has at least this many pages.
-      # @return [Mindee::V1::Parsing::Common::WorkflowResponse]
-      def execute_workflow(input_source, workflow_id, options: {})
-        opts = options.is_a?(WorkflowOptions) ? options : WorkflowOptions.new(params: options)
-        if opts.respond_to?(:page_options) && input_source.is_a?(Input::Source::LocalInputSource)
-          process_pdf_if_required(input_source, opts)
-        end
-
-        workflow_endpoint = V1::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(
-          input_source,
-          opts
-        )
-
-        Mindee::V1::Parsing::Common::WorkflowResponse.new(V1::Product::Universal::Universal, prediction, raw_http)
-      end
 
       # Load a prediction.
       #

data/lib/mindee/v1/http.rb

@@ -1,4 +1,3 @@
 # frozen_string_literal: true
 
-require_relative 'http/workflow_endpoint'
 require_relative 'http/endpoint'

data/lib/mindee/v1/product.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
 
-require_relative 'product/barcode_reader/barcode_reader_v1'
 require_relative 'product/cropper/cropper_v1'
 require_relative 'product/financial_document/financial_document_v1'
-require_relative 'product/fr/bank_account_details/bank_account_details_v1'
 require_relative 'product/fr/bank_account_details/bank_account_details_v2'
 require_relative 'product/fr/bank_statement/bank_statement_v2'
-require_relative 'product/fr/id_card/id_card_v1'
 require_relative 'product/fr/id_card/id_card_v2'
 require_relative 'product/international_id/international_id_v2'
 require_relative 'product/invoice/invoice_v4'