kreuzberg 4.0.0.pre.rc.6

data/spec/binding/plugins/ocr_backend_spec.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe 'OCR Backend Plugin System' do
+  let(:test_image) { test_document_path('images/invoice_image.png') }
+
+  describe 'registering custom OCR backend' do
+    it 'registers and uses custom OCR backend class' do
+      class MockOcrBackend
+        include Kreuzberg::OcrBackendProtocol
+
+        attr_reader :process_called, :received_config
+
+        def initialize
+          @process_called = false
+          @received_config = nil
+        end
+
+        def name
+          'mock-ocr'
+        end
+
+        def process_image(_image_bytes, config)
+          @process_called = true
+          @received_config = config
+          'Mocked OCR text from custom backend'
+        end
+      end
+
+      backend = MockOcrBackend.new
+      Kreuzberg.register_ocr_backend('mock-ocr', backend)
+
+      config = Kreuzberg::Config::Extraction.new(
+        force_ocr: true,
+        ocr: Kreuzberg::Config::Ocr.new(backend: 'mock-ocr')
+      )
+
+      result = Kreuzberg.extract_file_sync(test_image, config: config)
+
+      expect(backend.process_called).to be true
+      expect(result.content).to include('Mocked OCR text')
+    end
+
+    it 'passes correct configuration to OCR backend' do
+      class ConfigCapturingBackend
+        include Kreuzberg::OcrBackendProtocol
+
+        attr_reader :received_config
+
+        def name
+          'config-capture'
+        end
+
+        def process_image(_image_bytes, config)
+          @received_config = config
+          'OCR result'
+        end
+      end
+
+      backend = ConfigCapturingBackend.new
+      Kreuzberg.register_ocr_backend('config-capture', backend)
+
+      config = Kreuzberg::Config::Extraction.new(
+        force_ocr: true,
+        ocr: Kreuzberg::Config::Ocr.new(
+          backend: 'config-capture',
+          language: 'eng'
+        )
+      )
+
+      Kreuzberg.extract_file_sync(test_image, config: config)
+
+      expect(backend.received_config).to be_a(Hash)
+      expect(backend.received_config['backend']).to eq('config-capture')
+      expect(backend.received_config['language']).to eq('eng')
+    end
+  end
+
+  describe 'OCR backend receives correct parameters' do
+    it 'receives image bytes as binary data' do
+      class BytesCapturingBackend
+        include Kreuzberg::OcrBackendProtocol
+
+        attr_accessor :received_bytes
+
+        def name
+          'bytes-capture'
+        end
+
+        def process_image(image_bytes, _config)
+          self.class.instance_variable_set(:@received_bytes, image_bytes)
+          'OCR result'
+        end
+      end
+
+      backend = BytesCapturingBackend.new
+      Kreuzberg.register_ocr_backend('bytes-capture', backend)
+
+      config = Kreuzberg::Config::Extraction.new(
+        force_ocr: true,
+        ocr: Kreuzberg::Config::Ocr.new(backend: 'bytes-capture')
+      )
+
+      Kreuzberg.extract_file_sync(test_image, config: config)
+
+      received_bytes = BytesCapturingBackend.instance_variable_get(:@received_bytes)
+      expect(received_bytes).to be_a(String)
+      expect(received_bytes.encoding).to eq(Encoding::BINARY)
+      expect(received_bytes.length).to be_positive
+    end
+
+    it 'backend can return extracted text' do
+      class SimpleOcrBackend
+        include Kreuzberg::OcrBackendProtocol
+
+        def name
+          'simple-ocr'
+        end
+
+        def process_image(_image_bytes, _config)
+          'Invoice Total: $1,234.56'
+        end
+      end
+
+      backend = SimpleOcrBackend.new
+      Kreuzberg.register_ocr_backend('simple-ocr', backend)
+
+      config = Kreuzberg::Config::Extraction.new(
+        force_ocr: true,
+        ocr: Kreuzberg::Config::Ocr.new(backend: 'simple-ocr')
+      )
+
+      result = Kreuzberg.extract_file_sync(test_image, config: config)
+
+      expect(result.content).to include('Invoice Total')
+      expect(result.content).to include('1,234.56')
+    end
+  end
+
+  describe 'OCR backend with stateful processing' do
+    it 'maintains state across multiple invocations' do
+      class StatefulOcrBackend
+        include Kreuzberg::OcrBackendProtocol
+
+        attr_reader :call_count
+
+        def initialize
+          @call_count = 0
+        end
+
+        def name
+          'stateful-ocr'
+        end
+
+        def process_image(_image_bytes, _config)
+          @call_count += 1
+          "OCR call number #{@call_count}"
+        end
+      end
+
+      backend = StatefulOcrBackend.new
+      Kreuzberg.register_ocr_backend('stateful-ocr', backend)
+
+      config = Kreuzberg::Config::Extraction.new(
+        force_ocr: true,
+        ocr: Kreuzberg::Config::Ocr.new(backend: 'stateful-ocr')
+      )
+
+      Kreuzberg.extract_file_sync(test_image, config: config)
+      Kreuzberg.extract_file_sync(test_image, config: config)
+
+      expect(backend.call_count).to be >= 1
+    end
+  end
+
+  describe 'error handling' do
+    it 'propagates errors from OCR backend' do
+      class FailingOcrBackend
+        include Kreuzberg::OcrBackendProtocol
+
+        def name
+          'failing-ocr'
+        end
+
+        def process_image(_image_bytes, _config)
+          raise StandardError, 'OCR processing failed'
+        end
+      end
+
+      backend = FailingOcrBackend.new
+      Kreuzberg.register_ocr_backend('failing-ocr', backend)
+
+      config = Kreuzberg::Config::Extraction.new(
+        force_ocr: true,
+        ocr: Kreuzberg::Config::Ocr.new(backend: 'failing-ocr')
+      )
+
+      expect do
+        Kreuzberg.extract_file_sync(test_image, config: config)
+      end.to raise_error(StandardError, /OCR processing failed/)
+    end
+
+    it 'handles missing OCR backend gracefully' do
+      config = Kreuzberg::Config::Extraction.new(
+        force_ocr: true,
+        ocr: Kreuzberg::Config::Ocr.new(backend: 'nonexistent-backend')
+      )
+
+      expect do
+        Kreuzberg.extract_file_sync(test_image, config: config)
+      end.to raise_error
+    end
+  end
+
+  describe 'OCR backend protocol implementation' do
+    it 'requires name method' do
+      class InvalidBackendNoName
+        def process_image(_image_bytes, _config)
+          'text'
+        end
+      end
+
+      backend = InvalidBackendNoName.new
+
+      expect do
+        Kreuzberg.register_ocr_backend('invalid', backend)
+      end.to raise_error
+    end
+
+    it 'requires process_image method' do
+      class InvalidBackendNoProcess
+        def name
+          'invalid'
+        end
+      end
+
+      backend = InvalidBackendNoProcess.new
+
+      expect do
+        Kreuzberg.register_ocr_backend('invalid', backend)
+      end.to raise_error
+    end
+  end
+
+  describe 'OCR backend management' do
+    describe '.list_ocr_backends' do
+      it 'returns an array of backend names' do
+        backends = Kreuzberg.list_ocr_backends
+        expect(backends).to be_an(Array)
+      end
+
+      it 'includes registered backends' do
+        class ListTestBackend
+          include Kreuzberg::OcrBackendProtocol
+
+          def name
+            'list-test-backend'
+          end
+
+          def process_image(_image_bytes, _config)
+            'test'
+          end
+        end
+
+        backend = ListTestBackend.new
+        Kreuzberg.register_ocr_backend('list-test-backend', backend)
+
+        backends = Kreuzberg.list_ocr_backends
+        expect(backends).to include('list-test-backend')
+
+        Kreuzberg.unregister_ocr_backend('list-test-backend')
+      end
+    end
+
+    describe '.unregister_ocr_backend' do
+      it 'removes backend from registry' do
+        class UnregisterTestBackend
+          include Kreuzberg::OcrBackendProtocol
+
+          def name
+            'unregister-test'
+          end
+
+          def process_image(_image_bytes, _config)
+            'test'
+          end
+        end
+
+        backend = UnregisterTestBackend.new
+        Kreuzberg.register_ocr_backend('unregister-test', backend)
+
+        backends = Kreuzberg.list_ocr_backends
+        expect(backends).to include('unregister-test')
+
+        Kreuzberg.unregister_ocr_backend('unregister-test')
+
+        backends = Kreuzberg.list_ocr_backends
+        expect(backends).not_to include('unregister-test')
+      end
+
+      it 'accepts nonexistent backend name without error' do
+        expect { Kreuzberg.unregister_ocr_backend('nonexistent-backend-xyz') }.not_to raise_error
+      end
+    end
+  end
+end

data/spec/binding/plugins/postprocessor_spec.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe 'PostProcessor Plugin System' do
+  let(:test_pdf) { test_document_path('text/contract_test.txt') }
+
+  after do
+    Kreuzberg.clear_post_processors
+  end
+
+  describe 'registering post-processor as Proc' do
+    it 'registers and executes Proc post-processor during extraction' do
+      processor_called = false
+      processor = lambda do |result|
+        processor_called = true
+        result['content'] = result['content'].upcase
+        result
+      end
+
+      Kreuzberg.register_post_processor('upcase', processor)
+      result = Kreuzberg.extract_file_sync(test_pdf)
+
+      expect(processor_called).to be true
+      expect(result.content).to eq(result.content.upcase)
+    end
+
+    it 'allows post-processor to modify result content' do
+      processor = lambda do |result|
+        result['content'] = "[PROCESSED] #{result['content']}"
+        result
+      end
+
+      Kreuzberg.register_post_processor('prefix', processor)
+      result = Kreuzberg.extract_file_sync(test_pdf)
+
+      expect(result.content).to start_with('[PROCESSED]')
+    end
+
+    it 'allows post-processor to add metadata' do
+      processor = lambda do |result|
+        result['metadata']['custom_field'] = 'custom_value'
+        result['metadata']['word_count'] = result['content'].split.length
+        result
+      end
+
+      Kreuzberg.register_post_processor('metadata_adder', processor)
+      result = Kreuzberg.extract_file_sync(test_pdf)
+
+      expect(result.metadata['custom_field']).to eq('custom_value')
+      expect(result.metadata['word_count']).to be_positive
+    end
+  end
+
+  describe 'registering post-processor as class' do
+    it 'registers and executes class-based post-processor' do
+      class WordCountProcessor
+        include Kreuzberg::PostProcessorProtocol
+
+        def call(result)
+          word_count = result['content'].split.length
+          result['metadata']['word_count'] = word_count
+          result['metadata']['processor_name'] = 'WordCountProcessor'
+          result
+        end
+      end
+
+      processor = WordCountProcessor.new
+      Kreuzberg.register_post_processor('word_count', processor)
+      result = Kreuzberg.extract_file_sync(test_pdf)
+
+      expect(result.metadata['word_count']).to be_positive
+      expect(result.metadata['processor_name']).to eq('WordCountProcessor')
+    end
+
+    it 'allows class-based processor to transform content' do
+      class TruncateProcessor
+        include Kreuzberg::PostProcessorProtocol
+
+        def initialize(max_length)
+          @max_length = max_length
+        end
+
+        def call(result)
+          result['content'] = "#{result['content'][0...@max_length]}..." if result['content'].length > @max_length
+          result
+        end
+      end
+
+      processor = TruncateProcessor.new(50)
+      Kreuzberg.register_post_processor('truncate', processor)
+      result = Kreuzberg.extract_file_sync(test_pdf)
+
+      expect(result.content.length).to be <= 53
+    end
+  end
+
+  describe 'multiple post-processors' do
+    it 'executes multiple registered post-processors in order' do
+      processor1 = lambda do |result|
+        result['metadata']['processor1'] = 'executed'
+        result
+      end
+
+      processor2 = lambda do |result|
+        result['metadata']['processor2'] = 'executed'
+        result
+      end
+
+      Kreuzberg.register_post_processor('proc1', processor1)
+      Kreuzberg.register_post_processor('proc2', processor2)
+      result = Kreuzberg.extract_file_sync(test_pdf)
+
+      expect(result.metadata['processor1']).to eq('executed')
+      expect(result.metadata['processor2']).to eq('executed')
+    end
+  end
+
+  describe 'unregister_post_processor' do
+    it 'removes a registered post-processor by name' do
+      processor = lambda do |result|
+        result['metadata']['should_not_appear'] = 'value'
+        result
+      end
+
+      Kreuzberg.register_post_processor('removable', processor)
+      Kreuzberg.unregister_post_processor('removable')
+      result = Kreuzberg.extract_file_sync(test_pdf)
+
+      expect(result.metadata['should_not_appear']).to be_nil
+    end
+
+    it 'does not affect other registered post-processors' do
+      processor1 = lambda do |result|
+        result['metadata']['keep1'] = 'value1'
+        result
+      end
+
+      processor2 = lambda do |result|
+        result['metadata']['remove'] = 'value2'
+        result
+      end
+
+      processor3 = lambda do |result|
+        result['metadata']['keep3'] = 'value3'
+        result
+      end
+
+      Kreuzberg.register_post_processor('keep1', processor1)
+      Kreuzberg.register_post_processor('remove', processor2)
+      Kreuzberg.register_post_processor('keep3', processor3)
+
+      Kreuzberg.unregister_post_processor('remove')
+      result = Kreuzberg.extract_file_sync(test_pdf)
+
+      expect(result.metadata['keep1']).to eq('value1')
+      expect(result.metadata['remove']).to be_nil
+      expect(result.metadata['keep3']).to eq('value3')
+    end
+  end
+
+  describe 'clear_post_processors' do
+    it 'removes all registered post-processors' do
+      processor1 = lambda do |result|
+        result['metadata']['proc1'] = 'value1'
+        result
+      end
+
+      processor2 = lambda do |result|
+        result['metadata']['proc2'] = 'value2'
+        result
+      end
+
+      Kreuzberg.register_post_processor('proc1', processor1)
+      Kreuzberg.register_post_processor('proc2', processor2)
+
+      Kreuzberg.clear_post_processors
+      result = Kreuzberg.extract_file_sync(test_pdf)
+
+      expect(result.metadata['proc1']).to be_nil
+      expect(result.metadata['proc2']).to be_nil
+    end
+  end
+
+  describe 'error handling' do
+    it 'propagates errors from post-processor' do
+      processor = lambda do |_result|
+        raise StandardError, 'Post-processor error'
+      end
+
+      Kreuzberg.register_post_processor('failing', processor)
+
+      expect do
+        Kreuzberg.extract_file_sync(test_pdf)
+      end.to raise_error(StandardError, /Post-processor error/)
+    end
+
+    it 'handles post-processor that returns invalid result' do
+      processor = lambda do |_result|
+        'invalid return value'
+      end
+
+      Kreuzberg.register_post_processor('invalid', processor)
+
+      expect do
+        Kreuzberg.extract_file_sync(test_pdf)
+      end.to raise_error
+    end
+  end
+
+  describe 'list_post_processors' do
+    it 'returns empty array when no post-processors registered' do
+      Kreuzberg.clear_post_processors
+      processors = Kreuzberg.list_post_processors
+      expect(processors).to be_an(Array)
+      expect(processors).to be_empty
+    end
+
+    it 'returns post-processor names after registration' do
+      Kreuzberg.clear_post_processors
+      processor = lambda do |result|
+        result['content'] = result['content'].upcase
+        result
+      end
+      Kreuzberg.register_post_processor('test-processor', processor)
+      processors = Kreuzberg.list_post_processors
+      expect(processors).to include('test-processor')
+      Kreuzberg.clear_post_processors
+    end
+
+    it 'returns all registered post-processor names' do
+      Kreuzberg.clear_post_processors
+      processor1 = lambda do |result|
+        result
+      end
+      processor2 = lambda do |result|
+        result
+      end
+      processor3 = lambda do |result|
+        result
+      end
+
+      Kreuzberg.register_post_processor('processor-one', processor1)
+      Kreuzberg.register_post_processor('processor-two', processor2)
+      Kreuzberg.register_post_processor('processor-three', processor3)
+
+      processors = Kreuzberg.list_post_processors
+      expect(processors).to contain_exactly('processor-one', 'processor-two', 'processor-three')
+      Kreuzberg.clear_post_processors
+    end
+
+    it 'reflects changes after unregistration' do
+      Kreuzberg.clear_post_processors
+      processor = lambda do |result|
+        result
+      end
+      Kreuzberg.register_post_processor('temp-processor', processor)
+
+      processors_before = Kreuzberg.list_post_processors
+      expect(processors_before).to include('temp-processor')
+
+      Kreuzberg.unregister_post_processor('temp-processor')
+
+      processors_after = Kreuzberg.list_post_processors
+      expect(processors_after).not_to include('temp-processor')
+      Kreuzberg.clear_post_processors
+    end
+  end
+end