add client methods

Author: ianardee

src/main/java/com/mindee/v2/MindeeClient.java

@@ -3,12 +3,15 @@
 import com.mindee.MindeeException;
 import com.mindee.input.LocalInputSource;
 import com.mindee.input.URLInputSource;
+import com.mindee.v2.clientoptions.BaseAnnotationParameters;
 import com.mindee.v2.clientoptions.BaseProductParameters;
+import com.mindee.v2.clientoptions.BaseRagDocumentUploadParameters;
 import com.mindee.v2.clientoptions.BaseSearchParameters;
 import com.mindee.v2.clientoptions.PollingOptions;
 import com.mindee.v2.http.MindeeApiV2;
 import com.mindee.v2.http.MindeeHttpApiV2;
 import com.mindee.v2.http.MindeeHttpExceptionV2;
+import com.mindee.v2.parsing.BaseRagAnnotationResponse;
 import com.mindee.v2.parsing.BaseResponse;
 import com.mindee.v2.parsing.JobResponse;
 import com.mindee.v2.parsing.error.ErrorResponse;
@@ -277,6 +280,230 @@ public SearchResponse searchModels(String modelName, String modelType) {
       .reqGetSearch(ModelSearchParameters.builder().name(modelName).modelType(modelType).build());
   }
 
+  /**
+   * Not recommended for general use, prefer {@link #uploadAndGetRagDocument}.
+   * You will need to poll until the document is ready for use.
+   * Add a document to the RAG database.
+   *
+   * @param inputSource The file to upload.
+   * @param parameters RAG document upload parameters.
+   * @return an instance of {@link BaseRagAnnotationResponse}.
+   */
+  public <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationResponse uploadRagDocument(
+      LocalInputSource inputSource,
+      BaseRagDocumentUploadParameters<TAnnotationResponse> parameters
+  ) throws IOException {
+    logger.log(System.Logger.Level.INFO, "Adding a document to the RAG database");
+    return mindeeApi.reqPostRagDocument(parameters, inputSource);
+  }
+
+  /**
+   * Add a document to the RAG database, poll, and return the initial annotation.
+   *
+   * @param inputSource The file to upload.
+   * @param parameters RAG document upload parameters.
+   * @return an instance of {@link BaseRagAnnotationResponse}.
+   */
+  public <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationResponse uploadAndGetRagDocument(
+      LocalInputSource inputSource,
+      BaseRagDocumentUploadParameters<TAnnotationResponse> parameters
+  ) throws IOException, InterruptedException {
+    return uploadAndGetRagDocument(inputSource, parameters, null);
+  }
+
+  /**
+   * Add a document to the RAG database, poll, and return the initial annotation.
+   *
+   * @param inputSource The file to upload.
+   * @param parameters RAG document upload parameters.
+   * @param pollingOptions Polling options (if null, default options are used).
+   * @return an instance of {@link BaseRagAnnotationResponse}.
+   */
+  public <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationResponse uploadAndGetRagDocument(
+      LocalInputSource inputSource,
+      BaseRagDocumentUploadParameters<TAnnotationResponse> parameters,
+      PollingOptions pollingOptions
+  ) throws IOException, InterruptedException {
+    if (pollingOptions == null) {
+      pollingOptions = PollingOptions.builder().build();
+    }
+    TAnnotationResponse initialResponse = uploadRagDocument(inputSource, parameters);
+    if (!"Processing".equals(initialResponse.getStatus())) {
+      return initialResponse;
+    }
+    return pollForRagDocument(parameters.getResponseClass(), initialResponse, pollingOptions);
+  }
+
+  /**
+   * Not recommended for general use, prefer {@link #getReadyRagDocument}.
+   * You will need to poll until the document is ready for use.
+   * Get a document's info and annotations from the RAG database.
+   *
+   * @param responseClass The class of the response.
+   * @param documentId The document's ID.
+   * @return an instance of {@link BaseRagAnnotationResponse}.
+   */
+  public <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationResponse getRagDocument(
+      Class<TAnnotationResponse> responseClass,
+      String documentId
+  ) {
+    logger.log(System.Logger.Level.INFO, "Getting RAG document ID: {0}", documentId);
+    return mindeeApi.reqGetRagAnnotation(responseClass, documentId);
+  }
+
+  /**
+   * Get a document's info and annotations from the RAG database, polling if it is still processing.
+   *
+   * @param responseClass The class of the response.
+   * @param documentId The document's ID.
+   * @return an instance of {@link BaseRagAnnotationResponse}.
+   */
+  public <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationResponse getReadyRagDocument(
+      Class<TAnnotationResponse> responseClass,
+      String documentId
+  ) throws InterruptedException {
+    return getReadyRagDocument(responseClass, documentId, null);
+  }
+
+  /**
+   * Get a document's info and annotations from the RAG database, polling if it is still processing.
+   *
+   * @param responseClass The class of the response.
+   * @param documentId The document's ID.
+   * @param pollingOptions Polling options (if null, default options are used).
+   * @return an instance of {@link BaseRagAnnotationResponse}.
+   */
+  public <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationResponse getReadyRagDocument(
+      Class<TAnnotationResponse> responseClass,
+      String documentId,
+      PollingOptions pollingOptions
+  ) throws InterruptedException {
+    TAnnotationResponse initialResponse = getRagDocument(responseClass, documentId);
+    if (!"Processing".equals(initialResponse.getStatus())) {
+      return initialResponse;
+    }
+
+    if (pollingOptions == null) {
+      pollingOptions = PollingOptions.builder().build();
+    }
+    return pollForRagDocument(responseClass, initialResponse, pollingOptions);
+  }
+
+  /**
+   * Not recommended for general use, prefer {@link #updateAndGetRagAnnotation}.
+   * You will need to poll until the document is ready for use.
+   * Update a document's annotations in the RAG database.
+   *
+   * @param parameters Annotation parameters.
+   * @return an instance of {@link BaseRagAnnotationResponse}.
+   */
+  public <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationResponse updateRagAnnotation(
+      BaseAnnotationParameters<TAnnotationResponse> parameters
+  ) {
+    logger
+      .log(System.Logger.Level.INFO, "Updating RAG document ID: {0}", parameters.getDocumentId());
+    return mindeeApi.reqPatchRagAnnotation(parameters);
+  }
+
+  /**
+   * Update a document's annotations in the RAG database and poll until complete.
+   *
+   * @param parameters Annotation parameters.
+   * @return an instance of {@link BaseRagAnnotationResponse}.
+   */
+  public <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationResponse updateAndGetRagAnnotation(
+      BaseAnnotationParameters<TAnnotationResponse> parameters
+  ) throws InterruptedException {
+    return updateAndGetRagAnnotation(parameters, null);
+  }
+
+  /**
+   * Update a document's annotations in the RAG database and poll until complete.
+   *
+   * @param parameters Annotation parameters.
+   * @param pollingOptions Polling options (if null, default options are used).
+   * @return an instance of {@link BaseRagAnnotationResponse}.
+   */
+  public <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationResponse updateAndGetRagAnnotation(
+      BaseAnnotationParameters<TAnnotationResponse> parameters,
+      PollingOptions pollingOptions
+  ) throws InterruptedException {
+    TAnnotationResponse initialResponse = updateRagAnnotation(parameters);
+    if (!"Processing".equals(initialResponse.getStatus())) {
+      return initialResponse;
+    }
+
+    if (pollingOptions == null) {
+      pollingOptions = PollingOptions.builder().build();
+    }
+    return pollForRagDocument(parameters.getResponseClass(), initialResponse, pollingOptions);
+  }
+
+  /**
+   * Delete a document from the RAG database.
+   * For extraction models only.
+   *
+   * @param documentId The document's ID.
+   * @return true if successful.
+   */
+  public boolean deleteExtractionRagDocument(String documentId) {
+    logger.log(System.Logger.Level.INFO, "Deleting RAG document ID: {0}", documentId);
+    return mindeeApi.reqDeleteExtractionRagDocument(documentId);
+  }
+
+  /**
+   * Poll until the RAG document is finished processing or the max number of attempts is reached.
+   *
+   * @param responseClass The class of the response.
+   * @param initialResponse The initial annotation response.
+   * @param pollingOptions Polling options.
+   * @return an instance of {@link BaseRagAnnotationResponse}.
+   * @throws InterruptedException Throws if the thread is interrupted.
+   */
+  private <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationResponse pollForRagDocument(
+      Class<TAnnotationResponse> responseClass,
+      BaseRagAnnotationResponse initialResponse,
+      PollingOptions pollingOptions
+  ) throws InterruptedException {
+    logger
+      .log(System.Logger.Level.INFO, "Polling for RAG document ID: {0}", initialResponse.getId());
+    int maxRetries = pollingOptions.getMaxRetries() + 1;
+
+    logger
+      .log(
+        System.Logger.Level.DEBUG,
+        "Waiting {0} seconds before attempting to retrieve the result...",
+        pollingOptions.getInitialDelaySec()
+      );
+
+    interruptibleSleep(
+      (long) (pollingOptions.getInitialDelaySec() * 1000),
+      pollingOptions.getCancelToken()
+    );
+
+    String documentId = initialResponse.getId();
+    long intervalMillis = (long) (pollingOptions.getIntervalSec() * 1000);
+    int retryCount = 1;
+
+    while (retryCount < maxRetries) {
+      interruptibleSleep(intervalMillis, pollingOptions.getCancelToken());
+      logger.log(System.Logger.Level.DEBUG, "Poll attempt {0} of {1}", retryCount, maxRetries);
+
+      TAnnotationResponse response = getRagDocument(responseClass, documentId);
+      retryCount++;
+
+      String status = response.getStatus();
+      if ("Processing".equals(status)) {
+        continue;
+      } else if ("Failed".equals(status)) {
+        throw new MindeeException("RAG failed without an error payload.");
+      } else {
+        return response;
+      }
+    }
+    throw new MindeeException("RAG polling not complete after " + retryCount + " attempts.");
+  }
+
   /**
    * Common logic for polling an asynchronous job for local & url files.
    *

src/main/java/com/mindee/v2/clientoptions/BaseAnnotationParameters.java

@@ -36,7 +36,7 @@ protected BaseAnnotationParameters(Class<TAnnotationResponse> responseClass, Str
   /**
    * Gets the request parameters for the upload request.
    */
-  public abstract Map<String, String> getRequestParameters();
+  public abstract Map<String, Object> getRequestParameters();
 
   protected abstract static class BaseBuilder<T extends BaseBuilder<T>> {
     protected String documentId;

src/main/java/com/mindee/v2/clientoptions/BaseProductParameters.java

@@ -28,7 +28,7 @@ public abstract class BaseProductParameters {
 
   /**
    * Base constructor.
-   * 
+   *
    * @param modelId {@link #modelId}
    * @param alias {@link #alias}
    * @param webhookIds {@link #webhookIds}

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

@@ -181,7 +181,6 @@ public <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationRespon
   }
 
   @Override
-  @SuppressWarnings("unchecked")
   public <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationResponse reqGetRagAnnotation(
       Class<TAnnotationResponse> responseClass,
       String documentId
@@ -197,7 +196,7 @@ public <TAnnotationResponse extends BaseRagAnnotationResponse> TAnnotationRespon
     var get = new HttpGet(url);
 
     logger.log(System.Logger.Level.DEBUG, "HTTP GET to {0} ...", url);
-    return (TAnnotationResponse) executeAPIRequest(get, BaseRagAnnotationResponse.class);
+    return executeAPIRequest(get, responseClass);
   }
 
   @Override

src/main/java/com/mindee/v2/product/extraction/ragdocuments/AnnotatedBaseField.java

@@ -27,5 +27,4 @@ public class AnnotatedBaseField {
    */
   @JsonProperty("guidelines")
   private String guidelines;
-
 }

src/main/java/com/mindee/v2/product/extraction/ragdocuments/AnnotatedDynamicField.java

@@ -1,6 +1,7 @@
 package com.mindee.v2.product.extraction.ragdocuments;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonValue;
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.mindee.v2.parsing.inference.field.FieldType;
 import lombok.AllArgsConstructor;
@@ -9,48 +10,74 @@
 import lombok.NoArgsConstructor;
 
 /**
- * Return the field class dynamically. //[cite: 6]
+ * Return the field class dynamically.
  */
 @Getter
 @EqualsAndHashCode
 @JsonIgnoreProperties(ignoreUnknown = true)
 @AllArgsConstructor
 @NoArgsConstructor
-@JsonDeserialize(using = DynamicAnnotationFieldDeserializer.class) // [cite: 6]
+@JsonDeserialize(using = DynamicAnnotationFieldDeserializer.class)
 public class AnnotatedDynamicField {
 
   /**
-   * Value as a simple field. //[cite: 6]
+   * Value as a simple field.
    */
-  private AnnotatedSimpleField simpleField; // [cite: 6]
+  private AnnotatedSimpleField simpleField;
 
   /**
-   * Value as an object field. //[cite: 6]
+   * Value as an object field.
    */
-  private AnnotatedObjectField objectField; // [cite: 6]
+  private AnnotatedObjectField objectField;
 
   /**
-   * Value as a list field. //[cite: 6]
+   * Value as a list field.
    */
-  private AnnotatedListField listField; // [cite: 6]
+  private AnnotatedListField listField;
 
   /**
-   * The type of field. //[cite: 6]
+   * The type of field.
    */
-  private FieldType type; // [cite: 6]
+  private FieldType type;
 
   /**
-   * Default constructor. //[cite: 6]
+   * Constructor for a simple field.
    */
-  public AnnotatedDynamicField(
-      FieldType type,
-      AnnotatedSimpleField simpleField,
-      AnnotatedObjectField objectField,
-      AnnotatedListField listField
-  ) {
-    this.type = type; // [cite: 6]
-    this.simpleField = simpleField; // [cite: 6]
-    this.objectField = objectField; // [cite: 6]
-    this.listField = listField; // [cite: 6]
+  public AnnotatedDynamicField(AnnotatedSimpleField field) {
+    this.type = FieldType.SIMPLE_FIELD;
+    this.simpleField = field;
+    this.objectField = null;
+    this.listField = null;
+  }
+
+  /**
+   * Constructor for a list field.
+   */
+  public AnnotatedDynamicField(AnnotatedListField field) {
+    this.type = FieldType.LIST_FIELD;
+    this.simpleField = null;
+    this.objectField = null;
+    this.listField = field;
+  }
+
+  /**
+   * Constructor for an object field.
+   */
+  public AnnotatedDynamicField(AnnotatedObjectField field) {
+    this.type = FieldType.OBJECT_FIELD;
+    this.simpleField = null;
+    this.objectField = field;
+    this.listField = null;
+  }
+
+  @JsonValue
+  public AnnotatedBaseField getField() {
+    if (simpleField != null) {
+      return simpleField;
+    }
+    if (listField != null) {
+      return listField;
+    }
+    return objectField;
   }
 }