From 684c6e63dea0ff549e3528bb258227d4d05c4d73 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 6 Jun 2026 15:33:56 +0200
Subject: [PATCH] feat(search): add NL search domain records and OllamaClient
 interfaces

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../search/NlQueryInterpretation.java         | 22 +++++++++++++++++++
 .../search/NlSearchRequest.java               | 11 ++++++++++
 .../search/NlSearchResponse.java              | 12 ++++++++++
 .../familienarchiv/search/OllamaClient.java   |  5 +++++
 .../search/OllamaHealthClient.java            |  5 +++++
 .../familienarchiv/search/PersonHint.java     | 13 +++++++++++
 6 files changed, 68 insertions(+)
 create mode 100644 backend/src/main/java/org/raddatz/familienarchiv/search/NlQueryInterpretation.java
 create mode 100644 backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchRequest.java
 create mode 100644 backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchResponse.java
 create mode 100644 backend/src/main/java/org/raddatz/familienarchiv/search/OllamaClient.java
 create mode 100644 backend/src/main/java/org/raddatz/familienarchiv/search/OllamaHealthClient.java
 create mode 100644 backend/src/main/java/org/raddatz/familienarchiv/search/PersonHint.java

diff --git a/backend/src/main/java/org/raddatz/familienarchiv/search/NlQueryInterpretation.java b/backend/src/main/java/org/raddatz/familienarchiv/search/NlQueryInterpretation.java
new file mode 100644
index 00000000..5313f093
--- /dev/null
+++ b/backend/src/main/java/org/raddatz/familienarchiv/search/NlQueryInterpretation.java
@@ -0,0 +1,22 @@
+package org.raddatz.familienarchiv.search;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.time.LocalDate;
+import java.util.List;
+
+public record NlQueryInterpretation(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+        List<PersonHint> resolvedPersons,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+        List<PersonHint> ambiguousPersons,
+        LocalDate dateFrom,
+        LocalDate dateTo,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+        List<String> keywords,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+        String rawQuery,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+        boolean keywordsApplied
+) {
+}
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchRequest.java b/backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchRequest.java
new file mode 100644
index 00000000..0e9d3a9a
--- /dev/null
+++ b/backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchRequest.java
@@ -0,0 +1,11 @@
+package org.raddatz.familienarchiv.search;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+
+public record NlSearchRequest(
+        @NotBlank
+        @Size(min = 3, max = 500)
+        String query
+) {
+}
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchResponse.java b/backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchResponse.java
new file mode 100644
index 00000000..04e51bff
--- /dev/null
+++ b/backend/src/main/java/org/raddatz/familienarchiv/search/NlSearchResponse.java
@@ -0,0 +1,12 @@
+package org.raddatz.familienarchiv.search;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.raddatz.familienarchiv.document.DocumentSearchResult;
+
+public record NlSearchResponse(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+        DocumentSearchResult result,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+        NlQueryInterpretation interpretation
+) {
+}
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/search/OllamaClient.java b/backend/src/main/java/org/raddatz/familienarchiv/search/OllamaClient.java
new file mode 100644
index 00000000..c0c8f1da
--- /dev/null
+++ b/backend/src/main/java/org/raddatz/familienarchiv/search/OllamaClient.java
@@ -0,0 +1,5 @@
+package org.raddatz.familienarchiv.search;
+
+public interface OllamaClient {
+    NlQueryInterpretation parse(String query);
+}
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/search/OllamaHealthClient.java b/backend/src/main/java/org/raddatz/familienarchiv/search/OllamaHealthClient.java
new file mode 100644
index 00000000..9f1ad1d5
--- /dev/null
+++ b/backend/src/main/java/org/raddatz/familienarchiv/search/OllamaHealthClient.java
@@ -0,0 +1,5 @@
+package org.raddatz.familienarchiv.search;
+
+public interface OllamaHealthClient {
+    boolean isHealthy();
+}
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/search/PersonHint.java b/backend/src/main/java/org/raddatz/familienarchiv/search/PersonHint.java
new file mode 100644
index 00000000..61a0e0b9
--- /dev/null
+++ b/backend/src/main/java/org/raddatz/familienarchiv/search/PersonHint.java
@@ -0,0 +1,13 @@
+package org.raddatz.familienarchiv.search;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.util.UUID;
+
+public record PersonHint(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+        UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+        String displayName
+) {
+}