✨ add RAG search API

src/v2/clientOptions/baseParameters.ts → src/v2/clientOptions/baseProductParameters.ts

@@ -1,10 +1,9 @@
-import { FormData } from "undici";
 import { MindeeConfigurationError } from "@/errors/index.js";
 
 /**
  * Constructor parameters for BaseParameters and its subclasses.
  */
-export interface BaseParametersConstructor {
+export interface BaseProductParametersConstructor {
   modelId: string;
   alias?: string;
   webhookIds?: string[];
@@ -25,7 +24,7 @@ export interface BaseParametersConstructor {
  *   webhookIds: ["YOUR_WEBHOOK_ID_1", "YOUR_WEBHOOK_ID_2"],
  * };
  */
-export abstract class BaseParameters {
+export abstract class BaseProductParameters {
   /**
    * Model ID to use for the inference. **Required.**
    */
@@ -47,7 +46,7 @@ export abstract class BaseParameters {
    */
   closeFile?: boolean;
 
-  protected constructor(params: BaseParametersConstructor) {
+  protected constructor(params: BaseProductParametersConstructor) {
     if (params.modelId === undefined || params.modelId === null || params.modelId === "") {
       throw new MindeeConfigurationError("Model ID must be provided");
     }
@@ -58,20 +57,20 @@ export abstract class BaseParameters {
   }
 
   /**
-   * Returns the form data to send to the API.
-   * @returns A `FormData` object.
+   * Gets the request parameters for the enqueue request.
+   * @returns A `Record` mapping parameter names to their string values.
    */
-  getFormData(): FormData {
-    const form = new FormData();
+  getRequestParameters(): Record<string, string> {
+    const parameters: Record<string, string> = {};
 
-    form.set("model_id", this.modelId);
+    parameters["model_id"] = this.modelId;
 
     if (this.alias !== undefined && this.alias !== null) {
-      form.set("alias", this.alias);
+      parameters["alias"] = this.alias;
     }
     if (this.webhookIds && this.webhookIds.length > 0) {
-      form.set("webhook_ids", this.webhookIds.join(","));
+      parameters["webhook_ids"] = this.webhookIds.join(",");
     }
-    return form;
+    return parameters;
   }
 }

src/v2/clientOptions/baseSearchParameters.ts

@@ -0,0 +1,44 @@
+/**
+ * Constructor parameters for BaseSearchParameters and its subclasses.
+ */
+export interface BaseSearchParametersConstructor {
+  page?: number;
+  perPage?: number;
+}
+
+/**
+ * Base parameters for searches.
+ */
+export abstract class BaseSearchParameters {
+  /**
+   * 1-based page index.
+   */
+  page?: number;
+
+  /**
+   * Number of items per page.
+   */
+  perPage?: number;
+
+  protected constructor(params: BaseSearchParametersConstructor) {
+    this.page = params.page;
+    this.perPage = params.perPage;
+  }
+
+  /**
+   * Gets the request parameters for the search request.
+   * @returns A `Record` mapping parameter names to their string values.
+   */
+  getRequestParameters(): Record<string, string> {
+    const parameters: Record<string, string> = {};
+
+    if (this.page !== null && this.page !== undefined && this.page > 0) {
+      parameters["page"] = this.page.toString();
+    }
+    if (this.perPage !== null && this.perPage !== undefined && this.perPage > 0) {
+      parameters["per_page"] = this.perPage.toString();
+    }
+
+    return parameters;
+  }
+}

src/v2/clientOptions/index.ts

@@ -3,4 +3,5 @@ export type {
   PollingOptionsConstructor,
   TimerOptions,
 } from "./pollingOptions.js";
-export { BaseParameters } from "./baseParameters.js";
+export { BaseProductParameters } from "./baseProductParameters.js";
+export { BaseSearchParameters } from "./baseSearchParameters.js";

src/v2/http/mindeeApiV2.ts

@@ -1,6 +1,7 @@
 import { ApiSettings } from "./apiSettings.js";
 import { Dispatcher } from "undici";
-import { BaseParameters } from "@/v2/index.js";
+import { BaseProductParameters } from "@/v2/index.js";
+import { FormData } from "undici";
 import {
   BaseResponse,
   ErrorResponse,
@@ -60,9 +61,10 @@ export class MindeeApiV2 {
   async reqPostProductEnqueue(
     product: typeof BaseProduct,
     inputSource: InputSource,
-    params: BaseParameters
+    params: BaseProductParameters
   ): Promise<JobResponse> {
-    const form = params.getFormData();
+    const form = this.#paramsToFormData(params.getRequestParameters());
+
     if (inputSource instanceof LocalInputSource) {
       form.set("file", new Blob([inputSource.fileObject]), inputSource.filename);
     } else {
@@ -157,6 +159,14 @@ export class MindeeApiV2 {
     return this.#processResponse(response, product.responseClass) as InstanceType<P["responseClass"]>;
   }
 
+  #paramsToFormData(params: Record<string, string>): FormData {
+    const form = new FormData();
+    for (const [key, value] of Object.entries(params)) {
+      form.set(key, value);
+    }
+    return form;
+  }
+
   #processResponse<T extends BaseResponse>(
     result: BaseHttpResponse,
     responseClass: ResponseConstructor<T>,

src/v2/index.ts

@@ -7,5 +7,5 @@ export {
   ErrorResponse,
   LocalResponse,
 } from "./parsing/index.js";
-export type { BaseParameters, TimerOptions } from "./clientOptions/index.js";
+export type { BaseProductParameters, TimerOptions } from "./clientOptions/index.js";
 export { PollingOptions } from "./clientOptions/index.js";

src/v2/parsing/search/baseSearchResponse.ts

@@ -0,0 +1,32 @@
+import { StringDict } from "@/parsing/index.js";
+import { BaseResponse } from "@/v2/parsing/baseResponse.js";
+import { PaginationMetadata } from "./paginationMetadata.js";
+
+/** Constructor type for a search response class with a static slug property. */
+export type SearchResponseConstructor<T extends BaseSearchResponse> =
+  (new (serverResponse: any) => T) & { readonly slug: string };
+
+
+/**
+ * Base class for search responses.
+ */
+export abstract class BaseSearchResponse extends BaseResponse {
+  /**
+   * Pagination metadata.
+   */
+  public pagination: PaginationMetadata;
+
+  protected constructor(serverResponse: StringDict) {
+    super(serverResponse);
+    this.pagination = new PaginationMetadata(serverResponse["pagination"]);
+  }
+
+  protected abstract bodyLines(): string[];
+
+  toString(): string {
+    const lines: string[] = this.bodyLines();
+    lines.push("Pagination Metadata", "###################");
+    lines.push(this.pagination.toString());
+    return lines.join("\n");
+  }
+}

src/v2/parsing/search/index.ts

@@ -2,3 +2,8 @@ export { PaginationMetadata } from "./paginationMetadata.js";
 export { SearchModel } from "./searchModel.js";
 export { SearchResponse } from "./searchResponse.js";
 export { ModelWebhook } from "./modelWebhook.js";
+export { BaseSearchResponse } from "./baseSearchResponse.js";
+export type { SearchResponseConstructor } from "./baseSearchResponse.js";
+export { ModelSearchResponse } from "./modelSearchResponse.js";
+export { RagDocument } from "./ragDocument.js";
+export { RagDocumentSearchResponse } from "./ragDocumentSearchResponse.js";

src/v2/parsing/search/modelSearchResponse.ts

@@ -0,0 +1,24 @@
+import { StringDict } from "@/parsing/index.js";
+import { BaseSearchResponse } from "./baseSearchResponse.js";
+import { SearchModels } from "./searchModels.js";
+
+/**
+ * Models search response.
+ */
+export class ModelSearchResponse extends BaseSearchResponse {
+  static readonly slug = "models";
+
+  /**
+   * List of models returned by the search.
+   */
+  public models: SearchModels;
+
+  constructor(serverResponse: StringDict) {
+    super(serverResponse);
+    this.models = new SearchModels(serverResponse["models"] ?? []);
+  }
+
+  protected bodyLines(): string[] {
+    return ["Models", "#######", this.models.toString()];
+  }
+}

src/v2/parsing/search/ragDocument.ts

@@ -0,0 +1,53 @@
+import { StringDict } from "@/parsing/index.js";
+
+/**
+ * Individual RAG document information.
+ */
+export class RagDocument {
+  /**
+   * Unique identifier of the RAG document.
+   */
+  public id: string;
+
+  /**
+   * Model identifier linked to the RAG document.
+   */
+  public modelId: string;
+
+  /**
+   * Original filename of the uploaded document.
+   */
+  public filename: string;
+
+  /**
+   * Date and time of the document creation.
+   */
+  public createdAt: Date;
+
+  /**
+   * Number of times this document was used in an inference.
+   */
+  public totalMatches: number;
+
+  /**
+   * Date and time of the latest matching inference, if any.
+   */
+  public lastMatchAt?: Date;
+
+  /**
+   * Current status of the RAG document.
+   */
+  public status: string;
+
+  constructor(serverResponse: StringDict) {
+    this.id = serverResponse["id"];
+    this.modelId = serverResponse["model_id"];
+    this.filename = serverResponse["filename"];
+    this.createdAt = new Date(serverResponse["created_at"]);
+    this.totalMatches = serverResponse["total_matches"];
+    this.lastMatchAt = serverResponse["last_match_at"]
+      ? new Date(serverResponse["last_match_at"])
+      : undefined;
+    this.status = serverResponse["status"];
+  }
+}

src/v2/parsing/search/ragDocumentSearchResponse.ts

@@ -0,0 +1,24 @@
+import { StringDict } from "@/parsing/index.js";
+import { BaseSearchResponse } from "./baseSearchResponse.js";
+import { RagDocuments } from "@/v2/parsing/search/ragDocuments.js";
+
+/**
+ * RAG documents search response.
+ */
+export class RagDocumentSearchResponse extends BaseSearchResponse {
+  static readonly slug = "rag-documents";
+
+  /**
+   * Paginated list of matching RAG documents.
+   */
+  public ragDocuments: RagDocuments;
+
+  constructor(serverResponse: StringDict) {
+    super(serverResponse);
+    this.ragDocuments = new RagDocuments(serverResponse["rag_documents"] ?? []);
+  }
+
+  protected bodyLines(): string[] {
+    return ["RAG Documents", "################", this.ragDocuments.toString()];
+  }
+}

src/v2/parsing/search/ragDocuments.ts

@@ -0,0 +1,32 @@
+import { RagDocument } from "@/v2/parsing/search/ragDocument.js";
+import { StringDict } from "@/parsing/index.js";
+
+/**
+ * List of RAG documents.
+ */
+export class RagDocuments extends Array<RagDocument> {
+
+  constructor(serverResponse: StringDict) {
+    super();
+    this.push(...(serverResponse ?? []).map(
+      (item: StringDict) => new RagDocument(item)
+    ));
+  }
+
+  toString(): string {
+    if (this.length === 0) {
+      return "\n";
+    }
+    const lines: string[] = [];
+    for (const ragDocument of this) {
+      lines.push(`* :ID: ${ragDocument.id}`);
+      lines.push(`  :Model ID: ${ragDocument.modelId}`);
+      lines.push(`  :Filename: ${ragDocument.filename}`);
+      lines.push(`  :Created At: ${ragDocument.createdAt}`);
+      lines.push(`  :Total Matches: ${ragDocument.totalMatches}`);
+      lines.push(`  :Last Match At: ${ragDocument.lastMatchAt}`);
+      lines.push(`  :Status: ${ragDocument.status}`);
+    }
+    return lines.join("\n");
+  }
+}