mindee 4.6.0 → 4.7.0.pre.rc1

data/lib/mindee/parsing/v2/field/object_field.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'base_field'
+require_relative 'inference_fields'
+
+module Mindee
+  module Parsing
+    module V2
+      module Field
+        # A field containing a nested set of inference fields.
+        class ObjectField < BaseField
+          # @return [InferenceFields] Fields contained in the object.
+          attr_reader :fields
+
+          # @param raw_prediction [Hash] Raw server response hash.
+          # @param indent_level [Integer] Level of indentation for rst display.
+          def initialize(raw_prediction, indent_level = 0)
+            super
+
+            inner_fields = raw_prediction.fetch('fields', raw_prediction)
+            @fields = InferenceFields.new(inner_fields, @indent_level + 1)
+          end
+
+          # String representation of the object field.
+          # @return [String] String representation with newline prefix.
+          def to_s
+            return "\n" unless @fields && !@fields.empty?
+
+            "\n#{@fields.to_s(1)}"
+          end
+
+          # String representation suitable for list display.
+          # @return [String] String representation without leading spaces.
+          def to_s_from_list
+            return '' if @fields.nil?
+            return '' unless @fields && !@fields.empty?
+
+            field_str = @fields.to_s(2)
+            field_str.length > 4 ? (field_str[4..] || '') : ''
+          end
+
+          # String representation of a single object field
+          # @return [String] Multi-line string with proper indentation.
+          def single_str
+            return '' unless @fields && !@fields.empty?
+
+            out_str = ''
+            indent = ' ' * @indent_level
+
+            @fields.each do |field_key, field_value|
+              value_str = field_value && !field_value.to_s.empty? ? field_value.to_s : ''
+              out_str += "\n#{indent}  :#{field_key}: #{value_str}"
+            end
+
+            out_str
+          end
+
+          # String representation for multi-object display
+          # @return [String] Formatted string for list context.
+          def multi_str
+            return '' unless @fields && !@fields.empty?
+
+            out_str = ''
+            indent = ' ' * @indent_level
+            first = true
+
+            @fields.each do |field_key, field_value|
+              value_str = field_value ? field_value.to_s : ''
+
+              if first
+                out_str += "#{indent}:#{field_key}: #{value_str}"
+                first = false
+              else
+                out_str += "\n#{indent}    :#{field_key}: #{value_str}"
+              end
+            end
+
+            out_str
+          end
+
+          # Allow dot notation access to nested fields.
+          # @param method_name [Symbol] The method name (field key).
+          # @return [ObjectField, nil] The field or nil if not found.
+          def method_missing(method_name, ...)
+            if @fields.respond_to?(method_name)
+              @fields.send(method_name, ...)
+            else
+              super
+            end
+          end
+
+          # Check if method_missing should handle the method.
+          # @param method_name [Symbol] The method name.
+          # @return [Boolean] True if the method should be handled.
+          def respond_to_missing?(method_name, include_private = false)
+            @fields.respond_to?(method_name) || super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/parsing/v2/field/simple_field.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'base_field'
+
+module Mindee
+  module Parsing
+    module V2
+      module Field
+        # A simple field with a scalar value.
+        class SimpleField < BaseField
+          # @return [String, Integer, Float, Boolean, nil] Value contained in the field.
+          attr_reader :value
+
+          # @param server_response [Hash] Raw server response hash.
+          # @param indent_level [Integer] Level of indentation for rst display.
+          def initialize(server_response, indent_level = 0)
+            super
+            @value = server_response.key?('value') ? server_response['value'] : nil
+          end
+
+          # String representation of the field value.
+          # @return [String] String representation of the value.
+          def to_s
+            return '' if @value.nil?
+
+            if @value.is_a?(TrueClass) || @value.is_a?(FalseClass)
+              @value ? 'True' : 'False'
+            elsif @value.is_a?(Integer) || @value.is_a?(Float)
+              # NOTE: explicitly typing because steep is very, very dumb
+              num = @value # @type var num: Integer | Float
+              format_numeric_value(num)
+            else
+              @value.to_s
+            end
+          end
+
+          private
+
+          # Format numeric values to display '.0' in string reps.
+          # @param value [Numeric] The numeric value to format.
+          # @return [String] Formatted numeric string.
+          def format_numeric_value(value)
+            float_value = value.to_f
+
+            if float_value == float_value.to_i
+              format('%.1f', float_value)
+            else
+              formatted = format('%.5f', float_value)
+              formatted.sub(%r{\.?0+$}, '')
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'field/base_field'
+require_relative 'field/field_confidence'
+require_relative 'field/field_location'
+require_relative 'field/inference_fields'
+require_relative 'field/list_field'
+require_relative 'field/object_field'
+require_relative 'field/simple_field'

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'inference_model'
+require_relative 'inference_file'
+require_relative 'inference_result'
+
+module Mindee
+  module Parsing
+    module V2
+      # Complete data returned by an inference request.
+      class Inference
+        # @return [InferenceModel] Information about the model used.
+        attr_reader :model
+        # @return [InferenceFile] Information about the processed file.
+        attr_reader :file
+        # @return [InferenceResult] Result contents.
+        attr_reader :result
+        # @return [String] Identifier of the inference (when provided by API).
+        attr_reader :id
+
+        # @param server_response [Hash] Hash representation of the JSON returned by the service.
+        def initialize(server_response)
+          raise ArgumentError, 'server_response must be a Hash' unless server_response.is_a?(Hash)
+
+          @model  = InferenceModel.new(server_response['model'])
+          @file   = InferenceFile.new(server_response['file'])
+          @result = InferenceResult.new(server_response['result'])
+
+          @id = server_response['id']
+        end
+
+        # String representation.
+        # @return [String]
+        def to_s
+          [
+            'Inference',
+            '#########',
+            'Model',
+            '=====',
+            ":ID: #{@model.id}",
+            '',
+            @file.to_s,
+            @result.to_s,
+            '',
+          ].join("\n")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    module V2
+      # Information about a file returned in an inference.
+      class InferenceFile
+        # @return [String] File name.
+        attr_reader :name
+        # @return [String, nil] Optional alias for the file.
+        attr_reader :file_alias
+        # @return [Integer] Page count.
+        attr_reader :page_count
+        # @return [String] MIME type.
+        attr_reader :mime_type
+
+        # @param server_response [Hash] Raw JSON parsed into a Hash.
+        def initialize(server_response)
+          @name       = server_response['name']
+          @file_alias = server_response['alias']
+          @page_count = server_response['page_count']
+          @mime_type  = server_response['mime_type']
+        end
+
+        # String representation.
+        # @return [String]
+        def to_s
+          "File\n" \
+            "====\n" \
+            ":Name: #{@name}\n" \
+            ":Alias:#{" #{@file_alias}" if @file_alias}\n" \
+            ":Page Count: #{@page_count}\n" \
+            ":MIME Type: #{@mime_type}\n"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    module V2
+      # ID of the model that produced the inference.
+      class InferenceModel
+        # @return [String] Identifier of the model.
+        attr_reader :id
+
+        # @param server_response [Hash] Raw JSON parsed into a Hash.
+        def initialize(server_response)
+          @id = server_response['id']
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'common_response'
+require_relative 'inference'
+
+module Mindee
+  module Parsing
+    module V2
+      # HTTP response wrapper that embeds a V2 Inference.
+      class InferenceResponse < CommonResponse
+        # @return [Inference] Parsed inference payload.
+        attr_reader :inference
+
+        # @param server_response [Hash] Hash parsed from the API JSON response.
+        def initialize(server_response)
+          # CommonResponse takes care of the generic metadata (status, etc.)
+          super
+
+          @inference = Inference.new(server_response['inference'])
+        end
+
+        # String representation.
+        # @return [String]
+        def to_s
+          @inference.to_s
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'field/inference_fields'
+require_relative 'inference_result_options'
+
+module Mindee
+  module Parsing
+    module V2
+      # Wrapper for the result of a V2 inference request.
+      class InferenceResult
+        # @return [Mindee::Parsing::V2::Field::InferenceFields] Fields produced by the model.
+        attr_reader :fields
+        # @return [Mindee::Parsing::V2::InferenceResultOptions, nil] Optional extra data.
+        attr_reader :options
+
+        # @param server_response [Hash] Hash version of the JSON returned by the API.
+        def initialize(server_response)
+          raise ArgumentError, 'server_response must be a Hash' unless server_response.is_a?(Hash)
+
+          @fields = Field::InferenceFields.new(server_response['fields'])
+
+          return unless server_response.key?('options') && server_response['options']
+
+          @options = InferenceResultOptions.new(server_response['options'])
+        end
+
+        # String representation.
+        # @return [String]
+        def to_s
+          parts = [
+            'Fields',
+            '======',
+            @fields.to_s,
+          ]
+
+          if @options
+            parts += [
+              'Options',
+              '=======',
+              @options.to_s,
+            ]
+          end
+
+          parts.join("\n")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'raw_text'
+
+module Mindee
+  module Parsing
+    module V2
+      # Optional data returned alongside an inference.
+      class InferenceResultOptions
+        # @return [Array<RawText>] Collection of raw texts per page.
+        attr_reader :raw_texts
+
+        # @param server_response [Hash] Raw JSON parsed into a Hash.
+        def initialize(server_response)
+          raw = server_response['raw_texts']
+          @raw_texts = raw.is_a?(Array) ? raw.map { |rt| RawText.new(rt) } : []
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'error_response'
+require_relative 'job_webhook'
+
+module Mindee
+  module Parsing
+    module V2
+      # Metadata returned when polling a job (asynchronous request).
+      class Job
+        # @return [String] Unique job identifier.
+        attr_reader :id
+        # @return [DateTime, nil] Timestamp of creation.
+        attr_reader :created_at
+        # @return [String] Identifier of the model used.
+        attr_reader :model_id
+        # @return [String] Name of the processed file.
+        attr_reader :filename
+        # @return [String] Optional alias for the file.
+        attr_reader :alias
+        # @return [String, nil] Current status (submitted, processing, done, …).
+        attr_reader :status
+        # @return [String] URL to query for updated status.
+        attr_reader :polling_url
+        # @return [String, nil] URL that redirects to the final result once ready.
+        attr_reader :result_url
+        # @return [Array<JobWebhook>] Webhooks triggered by the job.
+        attr_reader :webhooks
+        # @return [ErrorResponse, nil] Error details when the job failed.
+        attr_reader :error
+
+        # @param server_response [Hash] Parsed JSON payload from the API.
+        def initialize(server_response)
+          raise ArgumentError, 'server_response must be a Hash' unless server_response.is_a?(Hash)
+
+          @id          = server_response['id']
+          @status      = server_response['status'] if server_response.key?('status')
+          unless server_response['error'].nil? || server_response['error'].empty?
+            @error = ErrorResponse.new(server_response['error'])
+          end
+          @created_at  = Time.iso8601(server_response['created_at'])
+          @model_id    = server_response['model_id']
+          @polling_url = server_response['polling_url']
+          @filename    = server_response['filename']
+          @result_url  = server_response['result_url']
+          @alias       = server_response['alias']
+          @webhooks = []
+          server_response['webhooks'].each do |webhook|
+            @webhooks.push JobWebhook.new(webhook)
+          end
+        end
+
+        # String representation.
+        # @return [String]
+        def to_s
+          lines = [
+            'Job',
+            '###',
+            ":ID: #{@id}",
+            ":CreatedAt: #{@created_at}",
+            ":ModelID: #{@model_id}",
+            ":Filename: #{@filename}",
+            ":Alias: #{@alias}",
+            ":Status: #{@status}",
+            ":PollingURL: #{@polling_url}",
+            ":ResultURL: #{@result_url}",
+          ]
+
+          lines << @error.to_s if @error
+
+          unless @webhooks.empty?
+            lines += [
+              '',
+              'Webhooks',
+              '=========',
+              @webhooks.map(&:to_s).join("\n\n"),
+            ]
+          end
+
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'common_response'
+require_relative 'job'
+
+module Mindee
+  module Parsing
+    module V2
+      # HTTP response wrapper that embeds a V2 job.
+      class JobResponse < CommonResponse
+        # @return [Job] Parsed job payload.
+        attr_reader :job
+
+        # @param server_response [Hash] Hash parsed from the API JSON response.
+        def initialize(server_response)
+          # CommonResponse takes care of the generic metadata (status, etc.)
+          super
+
+          @job = Job.new(server_response['job'])
+        end
+
+        # String representation.
+        # @return [String]
+        def to_s
+          @job.to_s
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# lib/mindee/parsing/v2/job_response_webhook.rb
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'error_response'
+
+module Mindee
+  module Parsing
+    module V2
+      # Information about a webhook created for a job response.
+      class JobWebhook
+        # @return [String] Identifier of the webhook.
+        attr_reader :id
+        # @return [DateTime, nil] Creation timestamp (or +nil+ when absent).
+        attr_reader :created_at
+        # @return [String] Webhook status.
+        attr_reader :status
+        # @return [ErrorResponse, nil] Error information when something failed.
+        attr_reader :error
+
+        # @param server_response [Hash] Raw JSON parsed into a Hash.
+        def initialize(server_response)
+          @id = server_response['id']
+          @created_at = parse_date(server_response['created_at'])
+          @status     = server_response['status']
+          @error      = ErrorResponse.new(server_response['error']) if server_response.key?('error')
+        end
+
+        # RST display.
+        #
+        # @return [String]
+        def to_s
+          parts = [
+            'JobResponseWebhook',
+            '##################',
+            ":ID: #{@id}",
+            ":CreatedAt: #{@created_at}",
+            ":Status: #{@status}",
+          ]
+
+          parts << @error.to_s if @error
+          parts.join("\n")
+        end
+
+        private
+
+        # Safely parse an ISO-8601 date/time string to DateTime.
+        # @param str [String, nil] The date string.
+        # @return [DateTime, nil]
+        def parse_date(str)
+          return nil if str.to_s.empty?
+
+          DateTime.iso8601(str || '')
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    module V2
+      # Raw text extracted from a given page.
+      class RawText
+        # @return [Integer] Page number where the text was found.
+        attr_reader :page
+        # @return [String] Text content.
+        attr_reader :content
+
+        # @param server_response [Hash] Raw JSON parsed into a Hash.
+        def initialize(server_response)
+          @page = server_response['page']
+          @content = server_response['content']
+        end
+      end
+    end
+  end
+end

data/lib/mindee/parsing/v2.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'v2/common_response'
+require_relative 'v2/error_response'
+require_relative 'v2/field'
+require_relative 'v2/inference'
+require_relative 'v2/inference_file'
+require_relative 'v2/inference_model'
+require_relative 'v2/inference_response'
+require_relative 'v2/inference_result'
+require_relative 'v2/inference_result_options'
+require_relative 'v2/job'
+require_relative 'v2/job_response'
+require_relative 'v2/job_webhook'
+require_relative 'v2/raw_text'

data/lib/mindee/pdf/extracted_pdf.rb

@@ -7,14 +7,14 @@ module Mindee
       # An extracted sub-Pdf.
       class ExtractedPDF
         # Byte contents of the pdf
-        # @return [StreamIO]
+        # @return [StringIO]
         attr_reader :pdf_bytes
 
         # Name of the file.
         # @return [String]
         attr_reader :filename
 
-        # @param pdf_bytes [StreamIO]
+        # @param pdf_bytes [StringIO]
         # @param filename [String]
         def initialize(pdf_bytes, filename)
           @pdf_bytes = pdf_bytes
@@ -50,7 +50,9 @@ module Mindee
         # Returns the current PDF object as a usable BytesInputSource.
         # @return [Mindee::Input::Source::BytesInputSource]
         def as_input_source
-          Mindee::Input::Source::BytesInputSource.new(@pdf_bytes.read, @filename)
+          raise Errors::MindeePDFError, 'Bytes object is nil.' if @pdf_bytes.nil?
+
+          Mindee::Input::Source::BytesInputSource.new(@pdf_bytes.read || '', @filename)
         end
       end
     end

data/lib/mindee/pdf/pdf_extractor.rb

@@ -29,7 +29,7 @@ module Mindee
 
         # Creates a new Pdf from pages and save it into a buffer.
         # @param page_indexes [Array<Integer>] List of page number to use for merging in the original Pdf.
-        # @return [StreamIO] The buffer containing the new Pdf.
+        # @return [StringIO] The buffer containing the new Pdf.
         def cut_pages(page_indexes)
           options = PageOptions.new(params: {
                                       page_indexes: page_indexes,
@@ -75,24 +75,28 @@ module Mindee
         # @return [Array<Mindee::PDF::PDFExtractor::ExtractedPDF>]
         def extract_invoices(page_indexes, strict: false)
           raise Errors::MindeePDFError, 'No indexes provided.' if page_indexes.empty?
+
           if page_indexes[0].is_a?(Array) && page_indexes[0].all? { |i| i.is_a?(Integer) }
-            return extract_sub_documents(page_indexes)
+            page_indexes_as_array = page_indexes # @type var page_indexes : Array[Array[Integer]]
+            return extract_sub_documents(page_indexes_as_array)
           end
-          return extract_sub_documents(page_indexes.map(&:page_indexes)) unless strict
+          p_ids = page_indexes # @type var page_indexes: Product::InvoiceSplitter::InvoiceSplitterV1InvoicePageGroups
+          return extract_sub_documents(p_ids.map(&:page_indexes)) unless strict
 
           correct_page_indexes = []
           current_list = []
           previous_confidence = nil
-          page_indexes.each_with_index do |page_index, i|
-            confidence = page_index.confidence
+          p_ids.each_with_index do |p_i, i|
+            page_index = p_i # @type var page_index: Product::InvoiceSplitter::InvoiceSplitterV1InvoicePageGroup
+            confidence = page_index.confidence.to_f
             page_list = page_index.page_indexes
 
             if confidence >= 0.5 && previous_confidence.nil?
               current_list = page_list
-            elsif confidence >= 0.5 && i < page_indexes.length - 1
+            elsif confidence >= 0.5 && i < p_ids.length - 1
               correct_page_indexes << current_list
               current_list = page_list
-            elsif confidence < 0.5 && i == page_indexes.length - 1
+            elsif confidence < 0.5 && i == p_ids.length - 1
               current_list.concat page_list
               correct_page_indexes << current_list
             else