✨ add RAG search API

Author: ianardee

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

@@ -2,14 +2,16 @@
 
 import com.mindee.input.LocalInputSource;
 import com.mindee.input.URLInputSource;
-import com.mindee.v2.clientoptions.BaseParameters;
+import com.mindee.v2.clientoptions.BaseProductParameters;
+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.CommonResponse;
 import com.mindee.v2.parsing.JobResponse;
 import com.mindee.v2.parsing.error.ErrorResponse;
+import com.mindee.v2.parsing.search.BaseSearchResponse;
 import com.mindee.v2.parsing.search.SearchResponse;
 import com.mindee.v2.product.extraction.ExtractionResponse;
 import java.io.IOException;
@@ -44,7 +46,7 @@ public MindeeClient(MindeeApiV2 mindeeApi) {
    */
   public JobResponse enqueue(
       LocalInputSource inputSource,
-      BaseParameters params
+      BaseProductParameters params
   ) throws IOException {
     return mindeeApi.reqPostEnqueue(inputSource, params);
   }
@@ -55,7 +57,10 @@ public JobResponse enqueue(
    * @param inputSource The URL input source to send.
    * @param params The parameters to send along with the file.
    */
-  public JobResponse enqueue(URLInputSource inputSource, BaseParameters params) throws IOException {
+  public JobResponse enqueue(
+      URLInputSource inputSource,
+      BaseProductParameters params
+  ) throws IOException {
     inputSource.validateSecure();
     return mindeeApi.reqPostEnqueue(inputSource, params);
   }
@@ -68,7 +73,7 @@ public JobResponse getJob(String jobId) {
     if (jobId == null || jobId.trim().isEmpty()) {
       throw new IllegalArgumentException("jobId must not be null or blank.");
     }
-    return mindeeApi.reqGetJob(jobId);
+    return mindeeApi.reqGetJobById(jobId);
   }
 
   /**
@@ -82,7 +87,7 @@ public <TResponse extends CommonResponse> TResponse getResult(
     if (inferenceId == null || inferenceId.trim().isEmpty()) {
       throw new IllegalArgumentException("inferenceId must not be null or blank.");
     }
-    return mindeeApi.reqGetResult(responseClass, inferenceId);
+    return mindeeApi.reqGetResultById(responseClass, inferenceId);
   }
 
   /**
@@ -96,7 +101,7 @@ public <TResponse extends CommonResponse> TResponse getResultFromUrl(
     if (inferenceUrl == null || inferenceUrl.trim().isEmpty()) {
       throw new IllegalArgumentException("inferenceUrl must not be null or blank.");
     }
-    return mindeeApi.reqGetResultFromUrl(responseClass, inferenceUrl);
+    return mindeeApi.reqGetResultByUrl(responseClass, inferenceUrl);
   }
 
   /**
@@ -112,7 +117,7 @@ public <TResponse extends CommonResponse> TResponse getResultFromUrl(
   public <TResponse extends CommonResponse> TResponse enqueueAndGetResult(
       Class<TResponse> responseClass,
       LocalInputSource inputSource,
-      BaseParameters params
+      BaseProductParameters params
   ) throws IOException, InterruptedException {
     return enqueueAndGetResult(
       responseClass,
@@ -136,7 +141,7 @@ public <TResponse extends CommonResponse> TResponse enqueueAndGetResult(
   public <TResponse extends CommonResponse> TResponse enqueueAndGetResult(
       Class<TResponse> responseClass,
       LocalInputSource inputSource,
-      BaseParameters params,
+      BaseProductParameters params,
       PollingOptions pollingOptions
   ) throws IOException, InterruptedException {
     JobResponse job = enqueue(inputSource, params);
@@ -156,7 +161,7 @@ public <TResponse extends CommonResponse> TResponse enqueueAndGetResult(
   public <TResponse extends CommonResponse> TResponse enqueueAndGetResult(
       Class<TResponse> responseClass,
       URLInputSource inputSource,
-      BaseParameters params
+      BaseProductParameters params
   ) throws IOException, InterruptedException {
     return enqueueAndGetResult(
       responseClass,
@@ -180,19 +185,33 @@ public <TResponse extends CommonResponse> TResponse enqueueAndGetResult(
   public <TResponse extends CommonResponse> TResponse enqueueAndGetResult(
       Class<TResponse> responseClass,
       URLInputSource inputSource,
-      BaseParameters params,
+      BaseProductParameters params,
       PollingOptions pollingOptions
   ) throws IOException, InterruptedException {
     inputSource.validateSecure();
     JobResponse job = enqueue(inputSource, params);
     return pollAndFetch(responseClass, job, pollingOptions);
   }
 
+  /**
+   * Search for resources matching the given criteria.
+   *
+   * @param searchParameters Search parameters
+   */
+  public <TSearchResponse extends BaseSearchResponse> TSearchResponse search(
+      Class<TSearchResponse> responseClass,
+      BaseSearchParameters searchParameters
+  ) {
+    return mindeeApi.search(responseClass, searchParameters);
+  }
+
   /**
    * Return all models.
    *
    * @return an instance of {@link SearchResponse}
+   * @deprecated Use {@link #search} instead.
    */
+  @Deprecated
   public SearchResponse searchModels() {
     return searchModels(null, null);
   }
@@ -202,7 +221,9 @@ public SearchResponse searchModels() {
    *
    * @param modelName name of the model to search for
    * @return an instance of {@link SearchResponse}
+   * @deprecated Use {@link #search} instead.
    */
+  @Deprecated
   public SearchResponse searchModels(String modelName) {
     return searchModels(modelName, null);
   }
@@ -213,7 +234,9 @@ public SearchResponse searchModels(String modelName) {
    * @param modelName name of the model to search for
    * @param modelType type of the model to search for
    * @return an instance of {@link SearchResponse}
+   * @deprecated Use {@link #search} instead.
    */
+  @Deprecated
   public SearchResponse searchModels(String modelName, String modelType) {
     return mindeeApi.reqGetSearchModels(modelName, modelType);
   }

…dee/v2/clientoptions/BaseParameters.java …clientoptions/BaseProductParameters.javasrc/main/java/com/mindee/v2/clientoptions/BaseParameters.java renamed to src/main/java/com/mindee/v2/clientoptions/BaseProductParameters.java src/main/java/com/mindee/v2/clientoptions/BaseParameters.java renamed to src/main/java/com/mindee/v2/clientoptions/BaseProductParameters.java

@@ -1,17 +1,20 @@
 package com.mindee.v2.clientoptions;
 
+import java.util.HashMap;
+import java.util.Map;
 import java.util.Objects;
 import lombok.Data;
-import org.apache.hc.client5.http.entity.mime.MultipartEntityBuilder;
 
 @Data
-public abstract class BaseParameters {
+public abstract class BaseProductParameters {
   /**
-   * Model ID to use for the inference (required).
+   * Model ID to use for the inference. Required.
    */
   protected final String modelId;
   /**
-   * Optional alias for the file.
+   * Optional: a free-form string to tag the request with your own identifier.
+   * For example, an internal document ID, reference number, or database key.
+   * If set, it will be included in the job and result responses.
    */
   protected final String alias;
   /**
@@ -20,15 +23,19 @@ public abstract class BaseParameters {
    */
   protected final String[] webhookIds;
 
-  public MultipartEntityBuilder buildHttpBody(MultipartEntityBuilder builder) {
-    builder.addTextBody("model_id", this.getModelId());
-    if (this.getAlias() != null) {
-      builder.addTextBody("alias", this.getAlias());
+  public Map<String, String> getRequestParameters() {
+    var parameters = new HashMap<String, String>();
+
+    parameters.put("model_id", this.getModelId());
+
+    if (this.getAlias() != null && !this.getAlias().isBlank()) {
+      parameters.put("alias", getAlias());
     }
     if (this.getWebhookIds().length > 0) {
-      builder.addTextBody("webhook_ids", String.join(",", this.getWebhookIds()));
+      parameters.put("webhook_ids", String.join(",", this.getWebhookIds()));
     }
-    return builder;
+
+    return parameters;
   }
 
   protected static abstract class BaseBuilder<T extends BaseBuilder<T>> {
@@ -42,7 +49,8 @@ protected T self() {
     }
 
     protected BaseBuilder(String modelId) {
-      this.modelId = Objects.requireNonNull(modelId, "modelId must not be null");
+      this.modelId = Objects
+        .requireNonNull(modelId, "The model ID is required in product parameters");
     }
 
     /** Set an alias for the uploaded document. */

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

@@ -0,0 +1,66 @@
+package com.mindee.v2.clientoptions;
+
+import java.util.HashMap;
+import java.util.Map;
+import lombok.Data;
+
+/**
+ * Base parameters for searches.
+ */
+@Data
+public abstract class BaseSearchParameters {
+  /**
+   * 1-based page index.
+   */
+  protected final Integer page;
+  /**
+   * Number of items per page.
+   */
+  protected final Integer perPage;
+
+  /**
+   * Gets the request parameters for the search request.
+   */
+  public Map<String, String> getRequestParameters() {
+    var parameters = new HashMap<String, String>();
+
+    if (this.getPage() != null && this.getPage() > 0) {
+      parameters.put("page", String.valueOf(getPage()));
+    }
+    if (this.getPerPage() != null && this.getPerPage() > 0) {
+      parameters.put("per_page", String.valueOf(getPerPage()));
+    }
+
+    return parameters;
+  }
+
+  protected static abstract class BaseBuilder<T extends BaseBuilder<T>> {
+    protected Integer page;
+    protected Integer perPage;
+
+    @SuppressWarnings("unchecked")
+    protected T self() {
+      return (T) this;
+    }
+
+    protected BaseBuilder() {
+    }
+
+    /**
+     * 1-based page index.
+     */
+    public T page(Integer page) {
+      this.page = page;
+      return self();
+    }
+
+    /**
+     * Number of items per page.
+     */
+    public T perPage(Integer perPage) {
+      this.perPage = perPage;
+      return self();
+    }
+  }
+
+}

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

@@ -4,11 +4,14 @@
 import com.mindee.http.MindeeApiCommon;
 import com.mindee.input.LocalInputSource;
 import com.mindee.input.URLInputSource;
-import com.mindee.v2.clientoptions.BaseParameters;
+import com.mindee.v2.clientoptions.BaseProductParameters;
+import com.mindee.v2.clientoptions.BaseSearchParameters;
 import com.mindee.v2.parsing.CommonResponse;
 import com.mindee.v2.parsing.JobResponse;
 import com.mindee.v2.parsing.error.ErrorResponse;
+import com.mindee.v2.parsing.search.BaseSearchResponse;
 import com.mindee.v2.parsing.search.SearchResponse;
+import com.mindee.v2.product.ProductAttributes;
 import java.io.IOException;
 
 /**
@@ -23,7 +26,7 @@ public abstract class MindeeApiV2 extends MindeeApiCommon {
    */
   public abstract JobResponse reqPostEnqueue(
       LocalInputSource inputSource,
-      BaseParameters options
+      BaseProductParameters options
   ) throws IOException;
 
   /**
@@ -34,22 +37,22 @@ public abstract JobResponse reqPostEnqueue(
    */
   public abstract JobResponse reqPostEnqueue(
       URLInputSource inputSource,
-      BaseParameters options
+      BaseProductParameters options
   ) throws IOException;
 
   /**
    * Attempts to poll the queue.
    *
    * @param jobId id of the job to get.
    */
-  public abstract JobResponse reqGetJob(String jobId);
+  public abstract JobResponse reqGetJobById(String jobId);
 
   /**
    * Retrieves the inference from a 302 redirect.
    *
    * @param inferenceId ID of the inference to poll.
    */
-  public abstract <TResponse extends CommonResponse> TResponse reqGetResult(
+  public abstract <TResponse extends CommonResponse> TResponse reqGetResultById(
       Class<TResponse> responseClass,
       String inferenceId
   );
@@ -58,17 +61,26 @@ public abstract <TResponse extends CommonResponse> TResponse reqGetResult(
    * Retrieves the inference from a given URL.
    * The inference will only be available after it has finished processing.
    */
-  public abstract <TResponse extends CommonResponse> TResponse reqGetResultFromUrl(
+  public abstract <TResponse extends CommonResponse> TResponse reqGetResultByUrl(
       Class<TResponse> responseClass,
       String inferenceUrl
   );
 
+  /**
+   * Retrieves a list of resources with the given criteria.
+   */
+  public abstract <TSearchResponse extends BaseSearchResponse> TSearchResponse search(
+      Class<TSearchResponse> responseClass,
+      BaseSearchParameters searchParameters
+  );
+
   /**
    * Retrieves a list of models.
    *
    * @param modelName search term for model name
    * @param modelType search term for model type
    */
+  @Deprecated
   public abstract SearchResponse reqGetSearchModels(String modelName, String modelType);
 
   /**
@@ -84,8 +96,10 @@ protected ErrorResponse makeUnknownError(int statusCode) {
     );
   }
 
-  protected ProductInfo getResponseProductInfo(Class<? extends CommonResponse> responseClass) {
-    var productInfo = responseClass.getAnnotation(ProductInfo.class);
+  protected ProductAttributes getResponseProductInfo(
+      Class<? extends CommonResponse> responseClass
+  ) {
+    var productInfo = responseClass.getAnnotation(ProductAttributes.class);
     if (productInfo == null) {
       throw new MindeeException(
         "The class " + responseClass.getSimpleName() + " is not annotated with @ProductInfo"
@@ -94,8 +108,10 @@ protected ProductInfo getResponseProductInfo(Class<? extends CommonResponse> res
     return productInfo;
   }
 
-  protected ProductInfo getParamsProductInfo(Class<? extends BaseParameters> responseClass) {
-    var productInfo = responseClass.getAnnotation(ProductInfo.class);
+  protected ProductAttributes getParamsProductInfo(
+      Class<? extends BaseProductParameters> responseClass
+  ) {
+    var productInfo = responseClass.getAnnotation(ProductAttributes.class);
     if (productInfo == null) {
       throw new MindeeException(
         "The class " + responseClass.getSimpleName() + " is not annotated with @ProductInfo"