✨ add RAG search API

[ianardee]

Description

• Add RAG search API and rework search API to be generic.
• Print all error details in case of server error.

Types of changes

• Docs change / refactoring / dependency upgrade
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Requires a change to the official Guide documentation.

[Copilot]

🟡 Changes recommended

There is a confirmed null-parameter path in the deprecated searchModels() API that can trigger an NPE in the new search implementation, and the PR also introduces breaking public API renames while being marked non-breaking.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a generalized V2 “search” capability to the Java SDK (including a new RAG documents search endpoint), and refactors V2 parameter/metadata plumbing and CLI output handling to support it consistently.

Changes:

• Introduces generic MindeeClient.search(...) + HTTP implementation (/search/{slug}) and adds model + RAG document search parameter/response types.
• Refactors V2 product parameters and product metadata annotation usage (BaseProductParameters, @ProductAttributes) and updates affected products accordingly.
• Adds/updates unit + integration tests and extends the CLI with search-models (refactored) and search-rag-docs.

File summaries

File	Description
src/test/java/com/mindee/v2/search/RagDocumentSearchTest.java	Adds local deserialization coverage for RAG document search responses.
src/test/java/com/mindee/v2/search/RagDocumentSearchIT.java	Adds integration coverage for the RAG document search endpoint.
src/test/java/com/mindee/v2/search/ModelSearchTest.java	Adds local deserialization coverage for model search responses.
src/test/java/com/mindee/v2/search/ModelSearchIT.java	Adds integration coverage for model search and legacy deprecated searchModels path.
src/test/java/com/mindee/v2/product/SplitIT.java	Refactors client variable name and adjusts expected split result assertion.
src/test/java/com/mindee/v2/product/CropIT.java	Refactors client variable name usage in crop integration tests.
src/test/java/com/mindee/v2/MindeeClientTest.java	Updates test fake API to new method names and new search abstraction.
src/main/java/com/mindee/v2/search/ragdocuments/RagDocumentSearchResponse.java	Adds typed response class for RAG document searches.
src/main/java/com/mindee/v2/search/ragdocuments/RagDocumentSearchParameters.java	Adds query parameter builder for RAG document searches.
src/main/java/com/mindee/v2/search/models/ModelSearchResponse.java	Adds typed response class for model searches.
src/main/java/com/mindee/v2/search/models/ModelSearchParameters.java	Adds query parameter builder for model searches.
src/main/java/com/mindee/v2/product/split/SplitResponse.java	Migrates product annotation to @ProductAttributes.
src/main/java/com/mindee/v2/product/split/params/SplitParameters.java	Migrates to BaseProductParameters and updates annotation usage.
src/main/java/com/mindee/v2/product/ProductAttributes.java	Introduces/renames product metadata annotation used for routing.
src/main/java/com/mindee/v2/product/ocr/params/OcrParameters.java	Migrates to BaseProductParameters and updates annotation usage.
src/main/java/com/mindee/v2/product/ocr/OcrResponse.java	Migrates product annotation to @ProductAttributes.
src/main/java/com/mindee/v2/product/extraction/params/ExtractionParameters.java	Migrates to request-parameter map approach and adds RAG-related parameters into request params.
src/main/java/com/mindee/v2/product/extraction/ExtractionResponse.java	Migrates product annotation to @ProductAttributes.
src/main/java/com/mindee/v2/product/crop/params/CropParameters.java	Migrates to BaseProductParameters and updates annotation usage.
src/main/java/com/mindee/v2/product/crop/CropResponse.java	Migrates product annotation to @ProductAttributes.
src/main/java/com/mindee/v2/product/classification/params/ClassificationParameters.java	Migrates to BaseProductParameters and updates annotation usage.
src/main/java/com/mindee/v2/product/classification/ClassificationResponse.java	Migrates product annotation to @ProductAttributes.
src/main/java/com/mindee/v2/parsing/search/SearchResponse.java	Deprecates legacy search response type by inheriting from new model search response.
src/main/java/com/mindee/v2/parsing/search/SearchRagDocuments.java	Adds container type + string rendering for RAG document search items.
src/main/java/com/mindee/v2/parsing/search/SearchRagDocument.java	Adds DTO for individual RAG document search items.
src/main/java/com/mindee/v2/parsing/search/SearchModels.java	Adds container type + string rendering for model search items.
src/main/java/com/mindee/v2/parsing/search/SearchModel.java	Updates model webhook field Javadoc.
src/main/java/com/mindee/v2/parsing/search/BaseSearchResponse.java	Adds shared base for search responses (pagination + formatting).
src/main/java/com/mindee/v2/parsing/error/ErrorResponse.java	Improves error formatting for display/logging.
src/main/java/com/mindee/v2/parsing/CommonResponse.java	Clarifies base response documentation.
src/main/java/com/mindee/v2/MindeeClient.java	Introduces generic search entrypoint and refactors deprecated model search methods.
src/main/java/com/mindee/v2/http/MindeeHttpExceptionV2.java	Changes exception to carry/format full ErrorResponse.
src/main/java/com/mindee/v2/http/MindeeHttpApiV2.java	Implements generic /search/{slug} and refactors request parameter handling.
src/main/java/com/mindee/v2/http/MindeeApiV2.java	Updates API surface for renamed methods and adds generic search contract.
src/main/java/com/mindee/v2/clientoptions/BaseSearchParameters.java	Adds shared base for search query params (page/per_page).
src/main/java/com/mindee/v2/clientoptions/BaseProductParameters.java	Refactors product enqueue parameters into a map-based representation.
src/main/java/com/mindee/v2/cli/SplitCommand.java	Updates CLI hook name to new summary output method.
src/main/java/com/mindee/v2/cli/SearchRagDocumentsCommand.java	Adds CLI command for searching RAG documents.
src/main/java/com/mindee/v2/cli/SearchModelsCommand.java	Refactors to use new search API + shared CLI output behavior.
src/main/java/com/mindee/v2/cli/OcrCommand.java	Updates CLI wording and summary hook name.
src/main/java/com/mindee/v2/cli/ExtractionCommand.java	Updates CLI wording and summary hook name; clarifies RAG flag help text.
src/main/java/com/mindee/v2/cli/CropCommand.java	Updates CLI wording and summary hook name.
src/main/java/com/mindee/v2/cli/ClassificationCommand.java	Updates CLI wording and summary hook name.
src/main/java/com/mindee/v2/cli/BaseInferenceCommand.java	Refactors inference commands to share output + API key handling via new BaseCommand.
src/main/java/com/mindee/v2/cli/BaseCommand.java	Adds shared API-key + output formatting behavior for V2 CLI commands.
src/main/java/com/mindee/MindeeException.java	Renames constructor parameter names for clarity.
src/main/java/com/mindee/CommandLineInterface.java	Registers new search-rag-docs command in the root CLI.

Review details

Suppressed comments (2)

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

• getRequestParameters() calls this.getWebhookIds().length, which will throw if webhookIds is null (possible via the generated constructor or builder setter). This should be null-safe or enforce non-null upfront.
  src/main/java/com/mindee/v2/product/ProductAttributes.java:16
• This PR renames/removes public types (@ProductInfo -> @ProductAttributes, BaseParameters -> BaseProductParameters). That is a source/binary breaking change for SDK users, but the PR metadata indicates this is non-breaking; either add deprecated compatibility shims/aliases or mark/release this as a breaking change.

• Files reviewed: 48/48 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

There are confirmed runtime/robustness bugs (invalid SearchResponse casts in deprecated APIs, nullable paging parameters causing auto-unboxing NPEs, and potential NPEs in request parameter/annotation handling).

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (4)

Previously missed (1) — in code that hasn't changed since the last review.

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

• webhookIds can be set to null via BaseBuilder.webhookIds(...), but getRequestParameters() unconditionally calls this.getWebhookIds().length, which will NPE. Either normalize null to an empty array in the builder or null-check before accessing length.

src/main/java/com/mindee/v2/cli/SearchRagDocumentsCommand.java:26

• The --filename option description mentions "model name" but this flag filters by filename; this is misleading in CLI help output.

  @Option(
      names = { "-f", "--filename" },
      description = "Filter by model name partial match (case insensitive)."
  )

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

• searchModels(String modelName) has the same invalid cast issue as searchModels(): the new generic search(...) call returns a ModelSearchResponse instance, which cannot be cast to SearchResponse.

  @Deprecated
  public SearchResponse searchModels(String modelName) {
    return (SearchResponse) search(ModelSearchParameters.builder().name(modelName).build());
  }

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

• searchModels(String modelName, String modelType) also returns (SearchResponse) search(...), which will ClassCastException because ModelSearchParameters targets ModelSearchResponse.class.

  @Deprecated
  public SearchResponse searchModels(String modelName, String modelType) {
    return (SearchResponse) search(
      ModelSearchParameters.builder().name(modelName).modelType(modelType).build()
    );

• Files reviewed: 48/48 changed files
• Comments generated: 3
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

It includes broad public API refactors (parameters, annotations, HTTP interface, deprecated search types) that can introduce source/binary compatibility breaks and require careful maintainers’ review.

Review details

Suppressed comments (2)

src/main/java/com/mindee/v2/search/ragdocuments/RagDocumentSearchParameters.java:80

• RagDocumentSearchParameters.Builder#filename accepts whitespace-only strings (since it only checks isEmpty()), which then requires additional handling later. Prefer isBlank() + trim() here so the built parameters are always normalized.
  src/main/java/com/mindee/v2/clientoptions/BaseProductParameters.java:36
• getRequestParameters() assumes webhookIds is non-null (getWebhookIds().length), but the field can be null if a caller constructs a concrete parameters instance with a null array. This would throw an NPE when building the request. Consider null-checking (treat null as empty) before accessing .length.

• Files reviewed: 48/48 changed files
• Comments generated: 6
• Review effort level: Lite