mindee 4.12.0 → 5.0.0.beta1

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V2
+    module Parsing
+      # Individual error item.
+      class ErrorItem
+        # @return [String, nil] A JSON Pointer to the location of the body property.
+        attr_reader :pointer
+        # @return [String, nil] Explicit information on the issue.
+        attr_reader :detail
+
+        # @param server_response [Hash] Raw JSON parsed into a Hash.
+        def initialize(server_response)
+          @pointer = server_response['pointer']
+          @detail = server_response['detail']
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V2
+    module Parsing
+      # Encapsulates information returned by the API when an error occurs.
+      class ErrorResponse
+        # @return [Integer] The HTTP status code returned by the server.
+        attr_reader :status
+        # @return [String] A human-readable explanation specific to the occurrence of the problem.
+        attr_reader :detail
+        # @return [String] A short, human-readable summary of the problem.
+        attr_reader :title
+        # @return [String] A machine-readable code specific to the occurrence of the problem.
+        attr_reader :code
+        # @return [Array<ErrorItem>] A list of explicit error details.
+        attr_reader :errors
+
+        # @param server_response [Hash] Raw JSON parsed into a Hash.
+        def initialize(server_response)
+          @status = server_response['status']
+          @detail = server_response['detail']
+          @title = server_response['title']
+          @code = server_response['code']
+          @errors = if server_response.key?('errors')
+                      server_response['errors'].map do |error|
+                        ErrorItem.new(error)
+                      end
+                    else
+                      []
+                    end
+        end
+
+        # String representation.
+        # @return [String]
+        def to_s
+          "HTTP #{@status} - #{@title} :: #{@code} - #{@detail}"
+        end
+
+        # Hash representation
+        # @return [Hash] Hash representation of the object.
+        def as_hash
+          {
+            status: @status,
+            detail: @detail,
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V2
+    module Parsing
+      # Field submodule for V2.
+      module Field
+        # Base class for V2 fields.
+        class BaseField
+          # @return [Integer] Level of indentation for rst display.
+          attr_reader :indent_level
+
+          # @return [FieldConfidence, nil] Confidence score for the field.
+          attr_reader :confidence
+
+          # @return [Array<FieldLocation>] List of locations the field was found at.
+          attr_reader :locations
+
+          # @param raw_prediction [Hash] Raw prediction hash.
+          # @param indent_level [Integer] Level of indentation for rst display.
+          def initialize(raw_prediction, indent_level = 0)
+            @indent_level = indent_level
+            confidence = raw_prediction['confidence']
+            @confidence = FieldConfidence.new(confidence) unless confidence.nil? || confidence.empty?
+
+            locations = raw_prediction['locations']
+            @locations = if locations.nil? || locations.empty?
+                           []
+                         else
+                           locations.map do |location|
+                             FieldLocation.new(location)
+                           end
+                         end
+          end
+
+          # Factory method to create appropriate field types.
+          # @param raw_prediction [Hash] Raw prediction hash.
+          # @param indent_level [Integer] Level of indentation for rst display.
+          # @return [BaseField] Appropriate field instance.
+          # @raise [MindeeError] If the field type isn't recognized.
+          def self.create_field(raw_prediction, indent_level = 0)
+            if raw_prediction.key?('items')
+              require_relative 'list_field'
+              return ListField.new(raw_prediction, indent_level)
+            end
+
+            if raw_prediction.key?('fields')
+              require_relative 'object_field'
+              return ObjectField.new(raw_prediction, indent_level)
+            end
+
+            if raw_prediction.key?('value')
+              require_relative 'simple_field'
+              return SimpleField.new(raw_prediction, indent_level)
+            end
+
+            raise Error::MindeeError, "Unrecognized field format in #{raw_prediction.to_json}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V2
+    module Parsing
+      module Field
+        # Confidence level of a field as returned by the V2 API.
+        class FieldConfidence
+          # @return [String] The confidence level value.
+          attr_reader :value
+
+          # Absolute certainty about the field's extraction.
+          CERTAIN = 'Certain'
+          # High certainty about the field's extraction.
+          HIGH = 'High'
+          # Medium certainty about the field's extraction.
+          MEDIUM = 'Medium'
+          # Low certainty about the field's extraction.
+          LOW = 'Low'
+
+          # List of valid values, as frozen strings.
+          VALID_VALUES = ['Certain', 'High', 'Medium', 'Low'].freeze
+
+          # @param value [String] The confidence level value.
+          # @raise [ArgumentError] If the value is not a valid confidence level.
+          def initialize(value)
+            case value
+            when 'Certain' then @value = CERTAIN
+            when 'High' then @value = HIGH
+            when 'Medium' then @value = MEDIUM
+            when 'Low' then @value = LOW
+            else
+              raise ArgumentError,
+                    "Invalid confidence level: '#{value}'. Must be one of: #{VALID_VALUES.join(', ')}"
+            end
+
+            @value = value
+          end
+
+          # String representation of the confidence level.
+          # @return [String] The confidence level value.
+          def to_s
+            @value
+          end
+
+          # String representation of the confidence level.
+          # @return [Integer] The confidence level value as an integer: 1 is LOW, 4 is HIGH.
+          def to_i
+            val_to_i(@value)
+          end
+
+          # Inspect method for debugging.
+          # @return [String] Debug representation.
+          def inspect
+            "#<#{self.class.name}:#{@value}>"
+          end
+
+          # Using 'case' breaks steep ...
+          # rubocop:disable Style/CaseLikeIf
+
+          # Equality of two FieldConfidence instances.
+          # @param other [String, Integer, FieldConfidence] The other confidence to compare.
+          # @return [Boolean] `true` if they have the same value.
+          def ==(other)
+            if other.is_a?(FieldConfidence)
+              @value == other.value
+            elsif other.is_a?(String)
+              @value == other
+            elsif other.is_a?(Integer)
+              to_i == other
+            else
+              raise ArgumentError, "Invalid type: #{other.class}"
+            end
+          end
+
+          # Greater than or equality of two FieldConfidence instances.
+          # @param other [String, Integer, FieldConfidence] The other confidence to compare.
+          def >=(other)
+            if other.is_a?(FieldConfidence)
+              to_i >= val_to_i(other.value)
+            elsif other.is_a?(String)
+              to_i >= val_to_i(other)
+            elsif other.is_a?(Integer)
+              to_i >= other
+            else
+              raise ArgumentError, "Invalid type: #{other.class}"
+            end
+          end
+
+          # less than or equality of two FieldConfidence instances.
+          # # @param other [String, Integer, FieldConfidence] The other confidence to compare.
+          def <=(other)
+            if other.is_a?(FieldConfidence)
+              to_i <= val_to_i(other.value)
+            elsif other.is_a?(String)
+              to_i <= val_to_i(other)
+            elsif other.is_a?(Integer)
+              to_i <= other
+            else
+              raise ArgumentError, "Invalid type: #{other.class}"
+            end
+          end
+
+          # rubocop:enable Style/CaseLikeIf
+
+          # Aliases for the comparison operators.
+          alias eql? ==
+          alias gteql? >=
+          alias lteql? <=
+
+          protected
+
+          def val_to_i(value)
+            case value
+            when CERTAIN then 4
+            when HIGH then 3
+            when MEDIUM then 2
+            when LOW then 1
+            else
+              raise ArgumentError,
+                    "Invalid confidence level: '#{value}'. Must be one of: #{VALID_VALUES.join(', ')}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative '../../../geometry/polygon'
+
+module Mindee
+  module V2
+    module Parsing
+      module Field
+        # Location of a field.
+        class FieldLocation
+          # @return [Mindee::Geometry::Polygon, nil] Polygon corresponding to the field location.
+          attr_reader :polygon
+
+          # @return [Integer, nil] Page on which the field is located.
+          attr_reader :page
+
+          # @param server_response [Hash] Raw server response hash.
+          def initialize(server_response)
+            @polygon = Mindee::Geometry::Polygon.new(server_response['polygon'])
+            @page = server_response['page']
+          end
+
+          # String representation of the polygon (empty string when none).
+          #
+          # @return [String]
+          def to_s
+            "#{polygon} on page #{page}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative 'base_field'
+
+module Mindee
+  module V2
+    module Parsing
+      module Field
+        # Represents a hash-like collection of inference fields, providing methods for
+        # retrieval and string representation.
+        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
+
+          # Get a field by key and ensure it is a SimpleField.
+          # @param key [String] Field key to retrieve.
+          # @return [SimpleField] The SimpleField.
+          # @raise [TypeError] If the field is not a SimpleField.
+          def get_simple_field(key)
+            field = self[key]
+            raise TypeError, "Field #{key} is not a SimpleField" unless field.is_a?(SimpleField)
+
+            field
+          end
+
+          # Get a field by key and ensure it is a ListField.
+          # @param key [String] Field key to retrieve.
+          # @return [ListField] The ListField.
+          # @raise [TypeError] If the field is not a ListField.
+          def get_list_field(key)
+            field = self[key]
+            raise TypeError, "Field #{key} is not a ListField" unless field.is_a?(ListField)
+
+            field
+          end
+
+          # Get a field by key and ensure it is an ObjectField.
+          # @param key [String] Field key to retrieve.
+          # @return [ObjectField] The ObjectField.
+          # @raise [TypeError] If the field is not an ObjectField.
+          def get_object_field(key)
+            field = self[key]
+            raise TypeError, "Field #{key} is not a ObjectField" unless field.is_a?(ObjectField)
+
+            field
+          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 = [] # @type var lines: Array[String]
+
+            each do |field_key, field_value|
+              line = "#{padding}:#{field_key}:"
+
+              case (field_value.class.name || '').split('::').last
+              when 'ListField', '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/v2/parsing/field/list_field.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative 'base_field'
+
+module Mindee
+  module V2
+    module Parsing
+      module Field
+        # Represents a field that contains a list of items.
+        class ListField < BaseField
+          # @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 Error::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
+
+          # Return only simple fields.
+          # @return [Array<SimpleField>] Simple fields contained in the list.
+          # @raise [TypeError] If the fields are not SimpleField.
+          def simple_items
+            fields = [] # @type var fields: Array[SimpleField]
+            @items.each do |item|
+              raise TypeError, "Invalid field type detected: #{item.class}" unless item.is_a?(SimpleField)
+
+              fields << item
+            end
+            fields
+          end
+
+          # Return only object fields.
+          # @return [Array<ObjectField>] Object fields contained in the list.
+          # @raise [TypeError] If the fields are not ObjectField.
+          def object_items
+            fields = [] # @type var fields: Array[ObjectField]
+            @items.each do |item|
+              raise TypeError, "Invalid field type detected: #{item.class}" unless item.is_a?(ObjectField)
+
+              fields << item
+            end
+            fields
+          end
+
+          # String representation of the list field.
+          # @return [String] Formatted string with bullet points for each item.
+          def to_s
+            return '' unless @items && !@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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative 'base_field'
+require_relative 'inference_fields'
+
+module Mindee
+  module V2
+    module Parsing
+      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
+
+          # Get a field by key and ensure it is a SimpleField.
+          # @param key [String] Field key to retrieve.
+          # @return [SimpleField] The SimpleField.
+          # @raise [TypeError] If the field is not a SimpleField.
+          def get_simple_field(key)
+            @fields.get_simple_field(key)
+          end
+
+          # Get a field by key and ensure it is a ListField.
+          # @param key [String] Field key to retrieve.
+          # @return [ListField] The ListField.
+          # @raise [TypeError] If the field is not a ListField.
+          def get_list_field(key)
+            field = @fields.get_list_field(key)
+            raise TypeError, "Field #{key} is not a ListField" unless field.is_a?(ListField)
+
+            field
+          end
+
+          # Get a field by key and ensure it is an ObjectField.
+          # @param key [String] Field key to retrieve.
+          # @return [ObjectField] The ObjectField.
+          # @raise [TypeError] If the field is not an ObjectField.
+          def get_object_field(key)
+            field = @fields.get_object_field(key)
+            raise TypeError, "Field #{key} is not an ObjectField" unless field.is_a?(ObjectField)
+
+            field
+          end
+
+          # Get all simple fields.
+          # @return [Hash<String, SimpleField>] Simple fields contained in the object.
+          def simple_fields
+            # @type var result: Hash[String, SimpleField]
+            result = @fields.select { |_, value| value.is_a?(SimpleField) } # rubocop:disable Style/RedundantAssignment
+            result
+          end
+
+          # Get all list fields.
+          # @return [Hash<String, ListField>] List fields contained in the object.
+          def list_fields
+            # @type var result: Hash[String, ListField]
+            result = @fields.select { |_, value| value.is_a?(ListField) } # rubocop:disable Style/RedundantAssignment
+            result
+          end
+
+          # Get all object fields.
+          # @return [Hash<String, ObjectField>] Object fields contained in the object.
+          def object_fields
+            # @type var result: Hash[String, ObjectField]
+            result = @fields.select { |_, value| value.is_a?(ObjectField) } # rubocop:disable Style/RedundantAssignment
+            result
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'base_field'
+
+module Mindee
+  module V2
+    module Parsing
+      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['value']
+            @value = if value.is_a?(Integer)
+                       value.to_f
+                     else
+                       value
+                     end
+          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)
+              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