fix(dotAI): update default threshold to 0.25

[ihoffmann-dot]

Summary

Updates dotAI default values to better reflect real-world usage.

• Set default embeddings search threshold from 0.5 to 0.25
• Sync CompletionsForm.Builder and EmbeddingsDTO.Builder hardcoded fallback defaults to match

Changed Files

Backend

• AppKeys.java — threshold default .5 → .25; new completionTextPrompt default
• CompletionsForm.java — Builder.threshold fallback .5f → .25f
• EmbeddingsDTO.java — @JsonProperty(defaultValue) annotation .5f → .25f

Frontend

• embeddingsSearchThreshold: 0.25

Notes

• The threshold change only affects requests that do not explicitly pass a threshold parameter. Any request or config that sets threshold explicitly is unaffected.

Related Issue

This PR fixes #35183
EPIC: dotAI Multi-Provider Support #33970

[claude]

Claude finished @ihoffmann-dot's task in 1m 21s —— View job

---

Code Review

A few hardcoded .5f fallbacks were missed — they will keep the old default for some call paths even after this PR lands.

Issues

1. dotCMS/src/main/java/com/dotcms/ai/db/EmbeddingsDTO.java:109 — EmbeddingsDTO.from(Map) still falls back to .5f when threshold isn't in the map (used by SearchTool.query(Map) and any caller building from a generic map). Inconsistent with the rest of the PR; should be .25f or, better, read from EMBEDDINGS_SEARCH_DEFAULT_THRESHOLD so we have a single source of truth.

   .withThreshold((Try.of(() -> Float.parseFloat((String) form.get("threshold"))).getOrElse(.5f)));

   Fix this →

2. dotCMS/src/main/java/com/dotcms/ai/viewtool/SearchTool.java:63 and :138 — the VTL viewtool ($dotAI.search.query(query, indexName) and $dotAI.search.related(...)) hardcodes .withThreshold(.5f). These are user-facing helpers invoked from Velocity templates, so VTL callers will silently keep using 0.5 while the REST API now uses 0.25 — exactly the kind of split-brain the PR set out to avoid. Either bump to .25f or remove the explicit call so the Builder picks up the config default.
   Fix this →

Worth noting (not blocking)

3. SearchResource.java:85 — @DefaultValue(".25") is hardcoded in the JAX-RS annotation. Annotations can't reference runtime config, so duplication here is hard to avoid, but it adds drift risk: a future operator-tunable change to EMBEDDINGS_SEARCH_DEFAULT_THRESHOLD won't update the GET endpoint unless someone remembers this line. Consider documenting the link with a // keep in sync with AppKeys.EMBEDDINGS_SEARCH_DEFAULT_THRESHOLD comment.

4. CompletionsForm.java:185 and EmbeddingsDTO.Builder.threshold (line 168) — same drift pattern: CompletionsForm.Builder uses a hardcoded .25f, while EmbeddingsDTO.Builder reads from config. Not introduced by this PR, but the inconsistency is now visible. Aligning both on the config read would remove one more constant.

5. PR description mentions "new completionTextPrompt default" in AppKeys.java, but commit 31acfe1f reverted that. The description is stale — worth tidying before merge.

Behavioral note

Lowering the threshold from 0.5 → 0.25 (cosine distance, <=> operator) makes default searches more permissive, returning more loosely-matched results. Make sure that's the intended UX shift; existing dashboards / saved searches that didn't explicitly set a threshold will start returning a larger set.

---

• Read changed files
• Check for inconsistencies / missed defaults — found 2 missed .5f fallbacks
• Check call sites / behavioral impact
• Post review
  • dot-ai-update-defaults