mindee 4.5.0 → 4.7.0.pre.rc1

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative 'base_field'
+
+module Mindee
+  module Parsing
+    module V2
+      module Field
+        # Collection of inference fields that extends Hash functionality.
+        class InferenceFields < Hash
+          # @return [Integer] Level of indentation for rst display.
+          attr_reader :indent_level
+
+          # @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()
+            @indent_level = indent_level
+
+            server_response.each do |key, value|
+              self[key.to_s] = BaseField.create_field(value, 1)
+            end
+          end
+
+          # Get a field by key with nil fallback.
+          # @param key [String] Field key to retrieve.
+          # @return [BaseField, nil] The field or nil if not found.
+          def get(key)
+            self[key]
+          end
+
+          # Allow dot notation access to fields.
+          # @param method_name [Symbol] The method name (field key).
+          # @return [BaseField, nil] The field or nil if not found.
+          def method_missing(method_name, *args, &block)
+            key = method_name.to_s
+            if key?(key)
+              self[key]
+            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)
+            key?(method_name.to_s) || super
+          end
+
+          # rubocop:disable Metrics/CyclomaticComplexity
+          # rubocop:disable Metrics/PerceivedComplexity
+          # Convert the fields to a string representation.
+          # @param indent [Integer, nil] Optional indentation level.
+          # @return [String] String representation of all fields.
+          def to_s(indent = 0)
+            return '' if empty?
+
+            indent ||= @indent_level
+            padding = '  ' * indent
+            lines = []
+
+            each do |field_key, field_value|
+              line = "#{padding}:#{field_key}:"
+
+              case (field_value.class.name || '').split('::').last
+              when 'ListField'
+                # Check if ListField has items and they're not empty
+                list_f = field_value # @type var list_f: ListField
+                if defined?(list_f.items) && list_f.items && !list_f.items.empty?
+                  line += list_f.to_s
+                end
+              when 'ObjectField'
+                line += field_value.to_s
+              when 'SimpleField'
+                # Check if SimpleField has a non-empty value
+                simple_f = field_value # @type var simple_f: SimpleField
+                if defined?(simple_f.value) && simple_f.value && !simple_f.value.to_s.empty?
+                  line += " #{simple_f}"
+                end
+              else
+                logger.debug("Unknown value was passed to the field creator: #{field_key} : #{field_value}")
+              end
+
+              lines << line
+            end
+
+            lines.join("\n").rstrip
+          end
+          # rubocop:enable Metrics/CyclomaticComplexity
+          # rubocop:enable Metrics/PerceivedComplexity
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative 'base_field'
+
+module Mindee
+  module Parsing
+    module V2
+      module Field
+        # Represents a field that contains a list of items.
+        class ListField < BaseField
+          include Enumerable
+          # @return [Array<ListField | ObjectField | SimpleField>] Items contained in the list.
+          attr_reader :items
+
+          # @param server_response [Hash] Raw server response hash.
+          # @param indent_level [Integer] Level of indentation for rst display.
+          # @raise [MindeeError] If the 'items' key is missing or not an array.
+          def initialize(server_response, indent_level = 0)
+            super
+
+            unless server_response.key?('items') && server_response['items'].is_a?(Array)
+              raise Errors::MindeeError,
+                    "Expected \"items\" to be an array in #{server_response.to_json}."
+            end
+
+            @items = []
+            server_response['items'].each do |item|
+              @items << BaseField.create_field(item, indent_level + 1)
+            end
+          end
+
+          # String representation of the list field.
+          # @return [String] Formatted string with bullet points for each item.
+          def to_s
+            return "\n" if @items.empty?
+
+            parts = ['']
+            @items.each do |item|
+              next unless item
+
+              parts << if item.is_a?(ObjectField)
+                         item.to_s_from_list
+                       else
+                         item.to_s
+                       end
+            end
+
+            parts.join("\n  * ")
+          end
+
+          # Check if the list is empty.
+          # @return [Boolean] True if the list has no items.
+          def empty?
+            @items.empty?
+          end
+
+          # Get the number of items in the list.
+          # @return [Integer] Number of items.
+          def size
+            @items.size
+          end
+
+          # Get the number of items in the list (alias for size).
+          # @return [Integer] Number of items.
+          def length
+            @items.length
+          end
+
+          # Get an item by index.
+          # @param index [Integer] The index of the item to retrieve.
+          # @return [BaseField, nil] The item at the given index.
+          def [](index)
+            @items[index]
+          end
+
+          # Iterator for Enumerator inheritance.
+          # NOTE: Untyped due to incomplete support in steep.
+          def each(&block)
+            return to_enum(:each) unless block_given?
+
+            @items.each(&block)
+            self
+          end
+        end
+      end
+    end
+  end
+end

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