marcus/pdf-umbenenner
1
0
Fork 0
Code Activity

M5 AP-002 Externen Prompt geladen und deterministische KI-Anfrage

Browse Source 
aufgebaut
This commit is contained in:
Marcus van Elst
2026-04-07 00:02:20 +02:00
parent c15fb6b18d
commit cd5b6253df
7 changed files with 654 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/service/AiRequestComposer.java Normal file
View File

@@ -0,0 +1,142 @@
package de.gecheckt.pdf.umbenenner.application.service;
import java.util.Objects;
import de.gecheckt.pdf.umbenenner.domain.model.AiRequestRepresentation;
import de.gecheckt.pdf.umbenenner.domain.model.PromptIdentifier;
/**
* Composes deterministic AI request representations from prompt and document text.
* <p>
* This service builds the exact request that will be sent to the AI service,
* ensuring that the composition is deterministic and reproducible across batch runs.
* The request is constructed from:
* <ul>
* <li>The loaded prompt content (from the external prompt file)</li>
* <li>The stable prompt identifier (derived from the prompt source)</li>
* <li>The extracted document text (already limited to max characters if needed)</li>
* <li>The exact character count that was sent (for traceability)</li>
* </ul>
* <p>
* <strong>Order and structure:</strong> The composition follows a fixed, documented order
* to ensure that another implementation would not need to guess how the prompt and document
* are combined. The prompt is presented first, followed by the document text, with clear
* structural markers to distinguish between them.
* <p>
* <strong>JSON-only response expectation:</strong> The request is constructed with the
* explicit expectation that the AI will respond with a JSON object containing:
* <ul>
* <li>{@code title} — mandatory, max 20 characters (base title)</li>
* <li>{@code reasoning} — mandatory, the AI's explanation</li>
* <li>{@code date} — optional, should be in YYYY-MM-DD format if present</li>
* </ul>
* <p>
* This service is stateless and thread-safe. It performs no I/O and makes no external calls.
*/
public class AiRequestComposer {
/**
* Composes a deterministic AI request representation.
* <p>
* The composition order is fixed:
* <ol>
* <li>Prompt content</li>
* <li>Separator: newline</li>
* <li>Prompt identifier (for reference/traceability)</li>
* <li>Separator: newline</li>
* <li>Document text section marker</li>
* <li>Document text content</li>
* </ol>
* <p>
* This fixed order ensures that:
* <ul>
* <li>The prompt guides the AI</li>
* <li>The document text is clearly separated and identified</li>
* <li>Another implementation knows exactly where each part begins</li>
* <li>The composition is deterministic and reproducible</li>
* </ul>
*
* @param promptIdentifier the stable identifier for this prompt; must not be null
* @param promptContent the prompt template content; must not be null
* @param documentText the extracted document text; must not be null
* @return an AiRequestRepresentation with sentCharacterCount set to documentText.length()
* @throws NullPointerException if any parameter is null
*/
public static AiRequestRepresentation compose(
PromptIdentifier promptIdentifier,
String promptContent,
String documentText) {
Objects.requireNonNull(promptIdentifier, "promptIdentifier must not be null");
Objects.requireNonNull(promptContent, "promptContent must not be null");
Objects.requireNonNull(documentText, "documentText must not be null");
// The complete request text is composed in a deterministic order:
// 1. Prompt content (instruction)
// 2. Newline separator
// 3. Prompt identifier (for reference)
// 4. Newline separator
// 5. Document text section marker
// 6. Newline separator
// 7. Document text content
//
// This order is fixed so that another implementation knows exactly where
// the prompt and document text are positioned.
StringBuilder requestBuilder = new StringBuilder();
requestBuilder.append(promptContent);
requestBuilder.append("\n");
requestBuilder.append("--- Prompt-ID: ").append(promptIdentifier.identifier()).append(" ---");
requestBuilder.append("\n");
requestBuilder.append("--- Document Text ---");
requestBuilder.append("\n");
requestBuilder.append(documentText);
// Record the exact character count of the document text that was included.
// This is the length of the document text (not the complete request).
int sentCharacterCount = documentText.length();
return new AiRequestRepresentation(
promptIdentifier,
promptContent,
documentText,
sentCharacterCount);
}
/**
* Constructs the complete request text that will be sent to the AI.
* <p>
* This is a helper method that builds the exact string that would be included in the
* HTTP request to the AI service. It follows the same deterministic order as
* {@link #compose(PromptIdentifier, String, String)}.
*
* @param promptIdentifier the stable identifier for this prompt; must not be null
* @param promptContent the prompt template content; must not be null
* @param documentText the extracted document text; must not be null
* @return the complete, deterministically-ordered request text for the AI
* @throws NullPointerException if any parameter is null
*/
public static String buildCompleteRequestText(
PromptIdentifier promptIdentifier,
String promptContent,
String documentText) {
Objects.requireNonNull(promptIdentifier, "promptIdentifier must not be null");
Objects.requireNonNull(promptContent, "promptContent must not be null");
Objects.requireNonNull(documentText, "documentText must not be null");
StringBuilder requestBuilder = new StringBuilder();
requestBuilder.append(promptContent);
requestBuilder.append("\n");
requestBuilder.append("--- Prompt-ID: ").append(promptIdentifier.identifier()).append(" ---");
requestBuilder.append("\n");
requestBuilder.append("--- Document Text ---");
requestBuilder.append("\n");
requestBuilder.append(documentText);
return requestBuilder.toString();
}
private AiRequestComposer() {
// Static utility class – no instances
}
}

2
pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/service/package-info.java
View File

@@ -20,6 +20,8 @@
* <li>{@link de.gecheckt.pdf.umbenenner.application.service.DocumentProcessingCoordinator}
* — Per-document idempotency, status/counter mapping and consistent
* two-level persistence</li>
* <li>{@link de.gecheckt.pdf.umbenenner.application.service.AiRequestComposer}
* — Deterministic composition of AI request representations from prompt and document text</li>
* </ul>
*
* <h2>Document processing flow ({@code DocumentProcessingCoordinator})</h2>

195
pdf-umbenenner-application/src/test/java/de/gecheckt/pdf/umbenenner/application/service/AiRequestComposerTest.java Normal file
View File

@@ -0,0 +1,195 @@
package de.gecheckt.pdf.umbenenner.application.service;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import org.junit.jupiter.api.Test;
import de.gecheckt.pdf.umbenenner.domain.model.AiRequestRepresentation;
import de.gecheckt.pdf.umbenenner.domain.model.PromptIdentifier;
/**
* Unit tests for {@link AiRequestComposer}.
*/
class AiRequestComposerTest {
@Test
void compose_shouldCreateAiRequestRepresentation() {
// Given
PromptIdentifier promptId = new PromptIdentifier("prompt_v1.txt");
String promptContent = "You are a helpful assistant.";
String documentText = "This is the document content.";
// When
AiRequestRepresentation result = AiRequestComposer.compose(promptId, promptContent, documentText);
// Then
assertThat(result.promptIdentifier()).isEqualTo(promptId);
assertThat(result.promptContent()).isEqualTo(promptContent);
assertThat(result.documentText()).isEqualTo(documentText);
assertThat(result.sentCharacterCount()).isEqualTo(documentText.length());
}
@Test
void compose_shouldSetSentCharacterCountToDocumentTextLength() {
// Given
PromptIdentifier promptId = new PromptIdentifier("prompt.txt");
String promptContent = "Prompt";
String documentText = "Document text with exactly 26 characters";
// When
AiRequestRepresentation result = AiRequestComposer.compose(promptId, promptContent, documentText);
// Then
assertThat(result.sentCharacterCount()).isEqualTo(documentText.length());
assertThat(result.sentCharacterCount()).isEqualTo(40); // "Document text with exactly 26 characters" has 40 chars
}
@Test
void compose_shouldHandleEmptyDocumentText() {
// Given
PromptIdentifier promptId = new PromptIdentifier("prompt.txt");
String promptContent = "Prompt";
String documentText = "";
// When
AiRequestRepresentation result = AiRequestComposer.compose(promptId, promptContent, documentText);
// Then
assertThat(result.documentText()).isEmpty();
assertThat(result.sentCharacterCount()).isZero();
}
@Test
void compose_shouldThrowNullPointerException_whenPromptIdentifierIsNull() {
// When & Then
assertThatThrownBy(
() -> AiRequestComposer.compose(null, "Prompt", "Document"))
.isInstanceOf(NullPointerException.class)
.hasMessage("promptIdentifier must not be null");
}
@Test
void compose_shouldThrowNullPointerException_whenPromptContentIsNull() {
// When & Then
assertThatThrownBy(
() -> AiRequestComposer.compose(new PromptIdentifier("id"), null, "Document"))
.isInstanceOf(NullPointerException.class)
.hasMessage("promptContent must not be null");
}
@Test
void compose_shouldThrowNullPointerException_whenDocumentTextIsNull() {
// When & Then
assertThatThrownBy(
() -> AiRequestComposer.compose(new PromptIdentifier("id"), "Prompt", null))
.isInstanceOf(NullPointerException.class)
.hasMessage("documentText must not be null");
}
@Test
void buildCompleteRequestText_shouldBuildDeterministicOrder() {
// Given
PromptIdentifier promptId = new PromptIdentifier("prompt_v2.txt");
String promptContent = "Analyze this document";
String documentText = "Document content here";
// When
String result = AiRequestComposer.buildCompleteRequestText(promptId, promptContent, documentText);
// Then
// Verify deterministic order: prompt, then identifier, then document text
assertThat(result)
.contains(promptContent)
.contains("Prompt-ID: prompt_v2.txt")
.contains("Document Text")
.contains(documentText);
// Verify order: prompt comes before identifier
int promptIndex = result.indexOf(promptContent);
int identifierIndex = result.indexOf("Prompt-ID:");
assertThat(promptIndex).isLessThan(identifierIndex);
// Verify order: identifier comes before document marker
int documentMarkerIndex = result.indexOf("Document Text");
assertThat(identifierIndex).isLessThan(documentMarkerIndex);
// Verify order: document marker comes before document text
int docTextIndex = result.indexOf(documentText);
assertThat(documentMarkerIndex).isLessThan(docTextIndex);
}
@Test
void buildCompleteRequestText_shouldIncludeStructuralMarkers() {
// Given
PromptIdentifier promptId = new PromptIdentifier("prompt.txt");
String promptContent = "Prompt";
String documentText = "Document";
// When
String result = AiRequestComposer.buildCompleteRequestText(promptId, promptContent, documentText);
// Then
assertThat(result).contains("--- Prompt-ID:");
assertThat(result).contains("---");
assertThat(result).contains("--- Document Text ---");
}
@Test
void buildCompleteRequestText_shouldThrowNullPointerException_whenPromptIdentifierIsNull() {
// When & Then
assertThatThrownBy(
() -> AiRequestComposer.buildCompleteRequestText(null, "Prompt", "Document"))
.isInstanceOf(NullPointerException.class)
.hasMessage("promptIdentifier must not be null");
}
@Test
void buildCompleteRequestText_shouldThrowNullPointerException_whenPromptContentIsNull() {
// When & Then
assertThatThrownBy(
() -> AiRequestComposer.buildCompleteRequestText(new PromptIdentifier("id"), null, "Document"))
.isInstanceOf(NullPointerException.class)
.hasMessage("promptContent must not be null");
}
@Test
void buildCompleteRequestText_shouldThrowNullPointerException_whenDocumentTextIsNull() {
// When & Then
assertThatThrownBy(
() -> AiRequestComposer.buildCompleteRequestText(new PromptIdentifier("id"), "Prompt", null))
.isInstanceOf(NullPointerException.class)
.hasMessage("documentText must not be null");
}
@Test
void compose_shouldProduceValidRepresentation_withMultilineContent() {
// Given
PromptIdentifier promptId = new PromptIdentifier("prompt.txt");
String promptContent = "Line 1\nLine 2\nLine 3";
String documentText = "Doc line 1\nDoc line 2";
// When
AiRequestRepresentation result = AiRequestComposer.compose(promptId, promptContent, documentText);
// Then
assertThat(result.promptContent()).isEqualTo(promptContent);
assertThat(result.documentText()).isEqualTo(documentText);
assertThat(result.sentCharacterCount()).isEqualTo(documentText.length());
}
@Test
void buildCompleteRequestText_shouldPreserveNewlines() {
// Given
PromptIdentifier promptId = new PromptIdentifier("id");
String promptContent = "Prompt\nwith\nnewlines";
String documentText = "Document\ntext";
// When
String result = AiRequestComposer.buildCompleteRequestText(promptId, promptContent, documentText);
// Then
assertThat(result).contains("Prompt\nwith\nnewlines");
assertThat(result).contains("Document\ntext");
}
}