✨ add support for RAG metadata and better errors (#215)

Author: sebastianMindee

lib/mindee/errors/mindee_http_error_v2.rb

@@ -1,25 +1,44 @@
 # frozen_string_literal: true
 
 require_relative 'mindee_error'
+require_relative '../parsing/v2/error_item'
 
 module Mindee
   module Errors
     # API V2 HttpError
     class MindeeHTTPErrorV2 < MindeeError
-      # @return [Integer]
+      # @return [Integer] The HTTP status code returned by the server.
       attr_reader :status
-      # @return [String]
+      # @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 http_error [Hash, Parsing::V2::ErrorResponse]
       def initialize(http_error)
         if http_error.is_a?(Parsing::V2::ErrorResponse)
           http_error = { 'detail' => http_error.detail,
-                         'status' => http_error.status }
+                         'status' => http_error.status,
+                         'title' => http_error.title,
+                         'code' => http_error.code,
+                         'errors' => http_error.errors }
         end
         @status = http_error['status']
         @detail = http_error['detail']
-        super("HTTP error: #{@status} - #{@detail}")
+        @title = http_error['title']
+        @code = http_error['code']
+        @errors = if http_error.key?('errors')
+                    http_error['errors'].map do |error|
+                      Parsing::V2::ErrorItem.new(error)
+                    end
+                  else
+                    []
+                  end
+        super("HTTP #{@status} - #{@title} :: #{@code} - #{@detail}")
       end
     end
   end

lib/mindee/errors/mindee_http_unknown_error_v2.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'mindee_error'
+
+module Mindee
+  module Errors
+    # Unknown HTTP error for the V2 API.
+    class MindeeHTTPUnknownErrorV2 < MindeeHTTPErrorV2
+      def initialize(http_error)
+        super({ 'detail' => "Couldn't deserialize server error. Found: #{http_error}",
+                'status' => -1,
+                'title' => 'Unknown Error',
+                'code' => '000-000',
+                'errors' => nil })
+      end
+    end
+  end
+end

lib/mindee/parsing/v2/error_item.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    module V2
+      # 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

lib/mindee/parsing/v2/error_response.rb

@@ -5,21 +5,36 @@ module Parsing
     module V2
       # Encapsulates information returned by the API when an error occurs.
       class ErrorResponse
-        # @return [Integer] HTTP status code.
+        # @return [Integer] The HTTP status code returned by the server.
         attr_reader :status
-        # @return [String] Error detail.
+        # @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
-          "Error\n=====\n:Status: #{@status}\n:Detail: #{@detail}"
+          "HTTP #{@status} - #{@title} :: #{@code} - #{@detail}"
         end
 
         # Hash representation

lib/mindee/parsing/v2/inference_result.rb

@@ -2,6 +2,7 @@
 
 require_relative 'field/inference_fields'
 require_relative 'raw_text'
+require_relative 'rag_metadata'
 
 module Mindee
   module Parsing
@@ -12,6 +13,8 @@ class InferenceResult
         attr_reader :fields
         # @return [Mindee::Parsing::V2::RawText, nil] Optional extra data.
         attr_reader :raw_text
+        # @return [Mindee::Parsing::V2::RAGMetadata, nil] Optional RAG metadata.
+        attr_reader :rag
 
         # @param server_response [Hash] Hash version of the JSON returned by the API.
         def initialize(server_response)
@@ -20,6 +23,7 @@ def initialize(server_response)
           @fields = Field::InferenceFields.new(server_response['fields'])
 
           @raw_text = server_response['raw_text'] ? RawText.new(server_response['raw_text']) : nil
+          @rag = (V2::RAGMetadata.new(server_response['rag']) if server_response.key?('rag') && server_response['rag'])
         end
 
         # String representation.

lib/mindee/parsing/v2/rag_metadata.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    module V2
+      # Metadata about the RAG operation.
+      class RAGMetadata
+        # The UUID of the matched document used during the RAG operation.
+        attr_accessor :retrieved_document_id
+
+        def initialize(server_response)
+          @retrieved_document_id = server_response.fetch('retrieved_document_id', nil)
+        end
+      end
+    end
+  end
+end

sig/mindee/errors/mindee_http_error_v2.rbs

@@ -3,9 +3,12 @@ module Mindee
   module Errors
     # API V2 HttpError
     class MindeeHTTPErrorV2 < MindeeError
-
       attr_reader detail: String
       attr_reader status: Integer
+      attr_reader code: String
+      attr_reader title: String
+      attr_reader errors: Array[Parsing::V2::ErrorItem]
+
       def initialize: (Hash[String, untyped] | Parsing::V2::ErrorResponse) -> void
     end
   end

sig/mindee/errors/mindee_http_unknown_error_v2.rbs

@@ -0,0 +1,9 @@
+# lib/mindee/errors/mindee_http_unknown_error_v2.rb
+module Mindee
+  module Errors
+    # Unknown HTTP error for the V2 API.
+    class MindeeHTTPUnknownErrorV2 < MindeeHTTPErrorV2
+      def initialize: (Hash[String|Symbol, untyped]) -> void
+    end
+  end
+end

sig/mindee/parsing/v2/error_item.rbs

@@ -0,0 +1,13 @@
+# lib/mindee/parsing/v2/error_item.rb
+module Mindee
+  module Parsing
+    module V2
+      class ErrorItem
+        attr_reader pointer: String
+        attr_reader detail: String|nil
+
+        def initialize: (Hash[String|Symbol, untyped]) -> void
+      end
+    end
+  end
+end

sig/mindee/parsing/v2/error_response.rbs

@@ -5,6 +5,9 @@ module Mindee
       class ErrorResponse
         attr_reader detail: String
         attr_reader status: Integer
+        attr_reader code: String
+        attr_reader title: String
+        attr_reader errors: Array[ErrorItem]
         def initialize: (Hash[String | Symbol, untyped]) -> void
 
         def as_hash: -> Hash[Symbol, String | Integer]