✨ add extra error information and rag metadata (#277)

Author: ianardee

src/main/java/com/mindee/http/MindeeApiV2.java

@@ -3,6 +3,7 @@
 import com.mindee.InferenceParameters;
 import com.mindee.input.LocalInputSource;
 import com.mindee.input.URLInputSource;
+import com.mindee.parsing.v2.ErrorResponse;
 import com.mindee.parsing.v2.InferenceResponse;
 import com.mindee.parsing.v2.JobResponse;
 import java.io.IOException;
@@ -44,4 +45,17 @@ public abstract JobResponse reqGetJob(
    * @param inferenceId ID of the inference to poll.
    */
   abstract public InferenceResponse reqGetInference(String inferenceId);
+
+  /**
+   * Creates an "unknown error" response from an HTTP status code.
+   */
+  protected ErrorResponse makeUnknownError(int statusCode) {
+    return new ErrorResponse(
+        "Unknown Error",
+        "The server returned an Unknown error.",
+        statusCode,
+        statusCode + "-000",
+        null
+    );
+  }
 }

src/main/java/com/mindee/http/MindeeHttpApiV2.java

@@ -236,7 +236,7 @@ private MindeeHttpExceptionV2 getHttpError(ClassicHttpResponse response) {
       ErrorResponse err = mapper.readValue(rawBody, ErrorResponse.class);
 
       if (err.getDetail() == null) {
-        err = new ErrorResponse("Unknown error", response.getCode());
+        err = makeUnknownError(response.getCode());
       }
       return new MindeeHttpExceptionV2(err.getStatus(), err.getDetail());
 
@@ -321,10 +321,10 @@ private <R extends CommonResponse> R deserializeOrThrow(
     try {
       err = mapper.readValue(body, ErrorResponse.class);
       if (err.getDetail() == null) {
-        err = new ErrorResponse("Unknown error", httpStatus);
+        err = makeUnknownError(httpStatus);
       }
     } catch (Exception ignored) {
-      err = new ErrorResponse("Unknown error", httpStatus);
+      err = makeUnknownError(httpStatus);
     }
     throw new MindeeHttpExceptionV2(err.getStatus(), err.getDetail());
   }

src/main/java/com/mindee/parsing/v2/ErrorItem.java

@@ -0,0 +1,30 @@
+package com.mindee.parsing.v2;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.AllArgsConstructor;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+/**
+ * Error item model.
+ */
+@Getter
+@EqualsAndHashCode
+@JsonIgnoreProperties(ignoreUnknown = true)
+@AllArgsConstructor
+@NoArgsConstructor
+public final class ErrorItem {
+  /**
+   * A JSON Pointer to the location of the body property.
+   */
+  @JsonProperty("pointer")
+  private String pointer;
+
+  /**
+   * Explicit information on the issue.
+   */
+  @JsonProperty("detail")
+  private String detail;
+}

src/main/java/com/mindee/parsing/v2/ErrorResponse.java

@@ -2,13 +2,14 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.List;
 import lombok.AllArgsConstructor;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 
 /**
- * Error information from the API.
+ * Error response detailing a problem. The format adheres to RFC 9457.
  */
 @Getter
 @EqualsAndHashCode
@@ -17,20 +18,38 @@
 @NoArgsConstructor
 public final class ErrorResponse {
   /**
-   * Detail relevant to the error.
+   * A short, human-readable summary of the problem.
+   */
+  @JsonProperty("title")
+  private String title;
+
+  /**
+   * A human-readable explanation specific to the occurrence of the problem.
    */
   @JsonProperty("detail")
   private String detail;
 
   /**
-   * HTTP error code.
+   * The HTTP status code returned by the server.
    */
   @JsonProperty("status")
   private int status;
 
+  /**
+   * A machine-readable code specific to the occurrence of the problem.
+   */
+  @JsonProperty("code")
+  private String code;
+
+  /**
+   * The HTTP status code returned by the server.
+   */
+  @JsonProperty("errors")
+  private List<ErrorItem> errors;
+
   /** For prettier display. */
   @Override
   public String toString() {
-    return "HTTP Status: " + status + " - " + detail;
+    return "HTTP " + status + " - " + title + " :: " + code + " - " + detail;
   }
 }

src/main/java/com/mindee/parsing/v2/InferenceResult.java

@@ -20,17 +20,23 @@
 public final class InferenceResult {
 
   /**
-   * Model fields.
+   * Extracted fields, the key corresponds to the field's name in the data schema.
    */
   @JsonProperty("fields")
   private InferenceFields fields;
 
   /**
-   * Options.
+   * Raw text extracted from all pages in the document.
    */
   @JsonProperty("raw_text")
   private RawText rawText;
 
+  /**
+   * RAG metadata.
+   */
+  @JsonProperty("rag")
+  private RagMetadata rag;
+
   @Override
   public String toString() {
     StringJoiner joiner = new StringJoiner("\n");

src/main/java/com/mindee/parsing/v2/RagMetadata.java

@@ -0,0 +1,22 @@
+package com.mindee.parsing.v2;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+/**
+ * RAG metadata.
+ */
+@Getter
+@JsonIgnoreProperties(ignoreUnknown = true)
+@AllArgsConstructor
+@NoArgsConstructor
+public final class RagMetadata {
+  /**
+   * The UUID of the matched document used during the RAG operation.
+   */
+  @JsonProperty("retrieved_document_id")
+  private String retrievedDocumentId;
+}

src/main/java/com/mindee/parsing/v2/RawText.java

@@ -16,7 +16,7 @@
 @AllArgsConstructor
 @NoArgsConstructor
 public class RawText {
-  /*
+  /**
    * Page Number the text was found on.
    */
   @JsonProperty("pages")

src/test/java/com/mindee/MindeeClientV2IT.java

@@ -20,7 +20,7 @@
 
 @TestInstance(TestInstance.Lifecycle.PER_CLASS)
 @Tag("integration")
-@DisplayName("MindeeClientV2 – integration tests (V2)")
+@DisplayName("MindeeV2 – Integration Tests")
 class MindeeClientV2IT {
 
   private MindeeClientV2 mindeeClient;

src/test/java/com/mindee/MindeeClientV2Test.java

@@ -19,7 +19,7 @@
 import static org.mockito.ArgumentMatchers.*;
 import static org.mockito.Mockito.*;
 
-@DisplayName("MindeeClientV2 – client / API interaction tests")
+@DisplayName("MindeeV2 – Client and API Tests")
 class MindeeClientV2Test {
   /**
    * Creates a fully mocked MindeeClientV2.

src/test/java/com/mindee/TestingUtilities.java

@@ -18,6 +18,10 @@ public static Path getV1ResourcePath(String filePath) {
     return Paths.get("src/test/resources/v1/" + filePath);
   }
 
+  public static Path getV2ResourcePath(String filePath) {
+    return Paths.get("src/test/resources/v2/" + filePath);
+  }
+
   public static String getV1ResourcePathString(String filePath) {
     return getV1ResourcePath(filePath).toString();
   }