✨ add text_context option to v2 inference (#217)

ianardee · web-flow · commit 9d296c724767 · 2025-11-20T18:44:58.000+01:00
diff --git a/lib/mindee/http/mindee_api_v2.rb b/lib/mindee/http/mindee_api_v2.rb
@@ -111,8 +111,25 @@ def inference_result_req_get(queue_id)
         poll("#{@settings.base_url}/inferences/#{queue_id}")
       end
 
+      # Handle parameters for the enqueue form
+      # @param form_data [Array] Array of form fields
+      # @param params [Input::InferenceParameters] Inference options.
+      def enqueue_form_options(form_data, params)
+        # deal with optional features
+        form_data.push(['rag', params.rag.to_s]) unless params.rag.nil?
+        form_data.push(['raw_text', params.raw_text.to_s]) unless params.raw_text.nil?
+        form_data.push(['polygon', params.polygon.to_s]) unless params.polygon.nil?
+        form_data.push(['confidence', params.confidence.to_s]) unless params.confidence.nil?
+        form_data.push ['file_alias', params.file_alias] if params.file_alias
+        form_data.push ['text_context', params.text_context] if params.text_context
+        unless params.webhook_ids.nil? || params.webhook_ids.empty?
+          form_data.push ['webhook_ids', params.webhook_ids.join(',')]
+        end
+        form_data
+      end
+
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
-      # @param params [Input::InferenceParameters] Parse options.
+      # @param params [Input::InferenceParameters] Inference options.
       # @return [Net::HTTPResponse, nil]
       def enqueue(input_source, params)
         uri = URI("#{@settings.base_url}/inferences/enqueue")
@@ -125,16 +142,9 @@ def enqueue(input_source, params)
                     end
         form_data.push(['model_id', params.model_id])
 
-        # deal with optional features
-        form_data.push(['rag', params.rag.to_s]) unless params.rag.nil?
-        form_data.push(['raw_text', params.raw_text.to_s]) unless params.raw_text.nil?
-        form_data.push(['polygon', params.polygon.to_s]) unless params.polygon.nil?
-        form_data.push(['confidence', params.confidence.to_s]) unless params.confidence.nil?
+        # deal with other parameters
+        form_data = enqueue_form_options(form_data, params)
 
-        form_data.push ['file_alias', params.file_alias] if params.file_alias
-        unless params.webhook_ids.nil? || params.webhook_ids.empty?
-          form_data.push ['webhook_ids', params.webhook_ids.join(',')]
-        end
         headers = {
           'Authorization' => @settings.api_key,
           'User-Agent' => @settings.user_agent,
diff --git a/lib/mindee/input/inference_parameters.rb b/lib/mindee/input/inference_parameters.rb
@@ -25,6 +25,10 @@ class InferenceParameters
       # @return [String, nil] Optional alias for the file.
       attr_reader :file_alias
 
+      # @return [String, nil] Additional text context used by the model during inference.
+      #   Not recommended, for specific use only.
+      attr_reader :text_context
+
       # @return [Array<String>, nil] Optional list of Webhooks IDs to propagate the API response to.
       attr_reader :webhook_ids
 
@@ -52,6 +56,7 @@ def initialize(
         confidence: nil,
         file_alias: nil,
         webhook_ids: nil,
+        text_context: nil,
         polling_options: nil,
         close_file: true
       )
@@ -64,6 +69,7 @@ def initialize(
         @confidence = confidence
         @file_alias = file_alias
         @webhook_ids = webhook_ids || []
+        @text_context = text_context
         @polling_options = get_clean_polling_options(polling_options)
         @close_file = close_file.nil? || close_file
         # rubocop:enable Metrics/ParameterLists
diff --git a/sig/mindee/http/mindee_api_v2.rbs b/sig/mindee/http/mindee_api_v2.rbs
@@ -13,6 +13,10 @@ module Mindee
       def inference_job_req_get: (String) -> Net::HTTPResponse
       def inference_result_req_get: (String) -> Net::HTTPResponse
       def enqueue: (Input::Source::LocalInputSource | Input::Source::URLInputSource, Input::InferenceParameters) -> Net::HTTPResponse?
+
+      private
+
+      def enqueue_form_options: (Array[untyped], Input::InferenceParameters) -> Array[untyped]
     end
   end
 end
diff --git a/sig/mindee/input/inference_parameters.rbs b/sig/mindee/input/inference_parameters.rbs
@@ -10,6 +10,7 @@ module Mindee
       attr_reader polygon: bool?
       attr_reader rag: bool?
       attr_reader raw_text: bool?
+      attr_reader text_context: String?
       attr_reader webhook_ids: Array[String]?
 
       def initialize: (
@@ -19,6 +20,7 @@ module Mindee
           ?polygon: bool?,
           ?confidence: bool?,
           ?file_alias: String?,
+          ?text_context: String?,
           ?webhook_ids: Array[String]?,
           ?polling_options: Hash[Symbol | String, untyped] | PollingOptions?,
           ?close_file: bool?
diff --git a/spec/v2/client_v2_integration.rb b/spec/v2/client_v2_integration.rb
@@ -17,7 +17,7 @@
         max_retries: 80
       )
 
-      params = Mindee::Input::InferenceParameters.new(
+      inference_params = Mindee::Input::InferenceParameters.new(
         model_id,
         rag: false,
         raw_text: true,
@@ -27,7 +27,7 @@
         polling_options: polling
       )
 
-      response = client.enqueue_and_get_inference(input, params)
+      response = client.enqueue_and_get_inference(input, inference_params)
 
       expect(response).not_to be_nil
       expect(response.inference).not_to be_nil
@@ -64,7 +64,7 @@
       src_path = File.join(V1_PRODUCT_DATA_DIR, 'financial_document', 'default_sample.jpg')
       input = Mindee::Input::Source::FileInputSource.new(File.open(src_path, 'rb'), 'default_sample.jpg')
 
-      params = Mindee::Input::InferenceParameters.new(
+      inference_params = Mindee::Input::InferenceParameters.new(
         model_id,
         raw_text: false,
         polygon: false,
@@ -73,7 +73,7 @@
         file_alias: 'ruby-integration-test'
       )
 
-      response = client.enqueue_and_get_inference(input, params)
+      response = client.enqueue_and_get_inference(input, inference_params)
       expect(response).not_to be_nil
 
       file = response.inference.file
@@ -111,19 +111,21 @@
       src_path = File.join(FILE_TYPES_DIR, 'pdf', 'blank_1.pdf')
       input = Mindee::Input::Source::FileInputSource.new(File.open(src_path, 'rb'), 'blank_1.pdf')
 
-      params = Mindee::Input::InferenceParameters.new('INVALID_MODEL_ID')
+      inference_params = Mindee::Input::InferenceParameters.new('INVALID_MODEL_ID')
 
       expect do
-        client.enqueue_inference(input, params)
+        client.enqueue_inference(input, inference_params)
       end.to raise_error(Mindee::Errors::MindeeHTTPErrorV2) { |e| expect(e.status).to eq(422) }
     end
 
     it 'raises MindeeHTTPErrorV2 (422) on invalid webhook id' do
       src_path = File.join(FILE_TYPES_DIR, 'pdf', 'blank_1.pdf')
       input = Mindee::Input::Source::FileInputSource.new(File.open(src_path, 'rb'), 'blank_1.pdf')
 
-      params = Mindee::Input::InferenceParameters.new(model_id,
-                                                      webhook_ids: ['INVALID_WEBHOOK_ID'])
+      params = Mindee::Input::InferenceParameters.new(
+        model_id,
+        webhook_ids: ['INVALID_WEBHOOK_ID']
+      )
 
       expect do
         client.enqueue_inference(input, params)
@@ -141,12 +143,13 @@
       src_path = File.join(FILE_TYPES_DIR, 'pdf', 'blank_1.pdf')
       input = Mindee::Input::Source::FileInputSource.new(File.open(src_path, 'rb'), 'blank_1.pdf')
 
-      params = Mindee::Input::InferenceParameters.new(model_id,
-                                                      webhook_ids: ['fc405e37-4ba4-4d03-aeba-533a8d1f0f21',
-                                                                    'fc405e37-4ba4-4d03-aeba-533a8d1f0f21'])
+      inference_params = Mindee::Input::InferenceParameters.new(
+        model_id,
+        webhook_ids: ['fc405e37-4ba4-4d03-aeba-533a8d1f0f21', 'fc405e37-4ba4-4d03-aeba-533a8d1f0f21']
+      )
 
       expect do
-        client.enqueue_inference(input, params)
+        client.enqueue_inference(input, inference_params)
       end.to raise_error(Mindee::Errors::MindeeHTTPErrorV2) { |e|
         expect(e.status).to eq(422)
         expect(e.code).to start_with('422-')
@@ -174,17 +177,20 @@
     it 'raises on invalid model ID' do
       expect do
         src_path = File.join(V1_PRODUCT_DATA_DIR, 'financial_document', 'default_sample.jpg')
-        input = Mindee::Input::Source::FileInputSource.new(File.open(src_path, 'rb'), 'default_sample.jpg')
+        input = Mindee::Input::Source::FileInputSource.new(
+          File.open(src_path, 'rb'),
+          'default_sample.jpg'
+        )
 
-        params = Mindee::Input::InferenceParameters.new(
+        inference_params = Mindee::Input::InferenceParameters.new(
           'fc405e37-4ba4-4d03-aeba-533a8d1f0f21',
           raw_text: false,
           polygon: false,
           confidence: false,
           rag: false,
           file_alias: 'ruby-integration-test'
         )
-        client.enqueue_and_get_inference(input, params)
+        client.enqueue_and_get_inference(input, inference_params)
       end.to raise_error(Mindee::Errors::MindeeHTTPErrorV2) { |e|
         expect(e.status).to eq(404)
         expect(e.code).to start_with('404-')
@@ -199,9 +205,9 @@
     it 'parses an URL input source without errors' do
       url_input = Mindee::Input::Source::URLInputSource.new(blank_pdf_url)
 
-      params = Mindee::Input::InferenceParameters.new(model_id)
+      inference_params = Mindee::Input::InferenceParameters.new(model_id)
 
-      response = client.enqueue_and_get_inference(url_input, params)
+      response = client.enqueue_and_get_inference(url_input, inference_params)
 
       expect(response).not_to be_nil
       expect(response.inference).not_to be_nil
diff --git a/spec/v2/client_v2_spec.rb b/spec/v2/client_v2_spec.rb
@@ -45,7 +45,12 @@ def stub_next_request_with(method, hash:, status_code: 0)
   it 'enqueue(path) raises MindeeHTTPErrorV2 on 4xx' do
     expect do
       stub_next_request_with(:enqueue, hash: JSON.generate(json400))
-      client.enqueue_inference(input_doc, model_id: 'dummy-model')
+      inference_params = Mindee::Input::InferenceParameters.new(
+        'dummy-model',
+        raw_text: false,
+        text_context: 'Hello my name is mud.'
+      )
+      client.enqueue_inference(input_doc, inference_params)
     end.to raise_error(Mindee::Errors::MindeeHTTPErrorV2) { |e|
       expect(e.status).to eq(400)
       expect(e.detail).to eq('Unsupported content.')
@@ -55,7 +60,8 @@ def stub_next_request_with(method, hash:, status_code: 0)
   it 'enqueue_and_get_inference(path) raises MindeeHTTPErrorV2 on 4xx' do
     expect do
       stub_next_request_with(:enqueue, hash: JSON.generate(json400))
-      client.enqueue_and_get_inference(input_doc, model_id: 'dummy-model')
+      inference_params = Mindee::Input::InferenceParameters.new('dummy-model')
+      client.enqueue_and_get_inference(input_doc, inference_params)
     end.to raise_error(Mindee::Errors::MindeeHTTPErrorV2) { |e|
       expect(e.status).to eq(400)
       expect(e.detail).to eq('Unsupported content.')
@@ -67,7 +73,8 @@ def stub_next_request_with(method, hash:, status_code: 0)
 
     expect do
       stub_next_request_with(:enqueue, hash: JSON.generate(error_hash))
-      client.enqueue_inference(input_doc, model_id: 'dummy-model')
+      inference_params = Mindee::Input::InferenceParameters.new('dummy-model')
+      client.enqueue_inference(input_doc, inference_params)
     end.to raise_error(Mindee::Errors::MindeeHTTPErrorV2) { |e|
       expect(e.status).to eq(413)
       expect(e.detail).to include('File exceeds size limit')
