Add LLM-assisted NPC normalization

internal/modules/dnd/normalize/npcs/normalizer_test.go

@@ -2,6 +2,7 @@ package npcs
 
 import (
 	"context"
+	"encoding/json"
 	"reflect"
 	"strings"
 	"testing"
@@ -28,11 +29,14 @@ func TestModuleContractAndIdentity(t *testing.T) {
 	if err := Register(registry); err != nil {
 		t.Fatalf("Register() error = %v", err)
 	}
-	normalizer := New(Options{})
-	if metadata := normalizer.ManifestMetadata(); metadata["identity_policy"] != identity.Policy || metadata["normalization_policy"] != normalizationPolicy {
+	if _, err := New(nil, Options{}); err == nil {
+		t.Fatal("New(nil, Options{}) error = nil, want nil client rejection")
+	}
+	normalizer := newNormalizer(t, &recordingNPCNormalizerClient{})
+	if metadata := normalizer.ManifestMetadata(); metadata["identity_policy"] != identity.Policy || metadata["normalization_policy"] != normalizationPolicy || metadata["prompt_id"] != PromptID || metadata["semantic_context_policy"] != semanticContextPolicy || metadata["semantic_context_radius"] != semanticContextRadius {
 		t.Fatalf("metadata = %#v", metadata)
 	}
-	wantFingerprints := []pipeline.CheckpointFingerprint{{Name: "identity_policy", Value: identity.Policy}, {Name: "normalization_policy", Value: normalizationPolicy}}
+	wantFingerprints := []pipeline.CheckpointFingerprint{{Name: "prompt", Value: normalizer.promptSHA}, {Name: "response_schema", Value: normalizer.responseSchemaSHA}, {Name: "identity_policy", Value: identity.Policy}, {Name: "normalization_policy", Value: normalizationPolicy}, {Name: "semantic_context_policy", Value: semanticContextPolicy + ":2"}}
 	if got := normalizer.CheckpointFingerprints(); !reflect.DeepEqual(got, wantFingerprints) {
 		t.Fatalf("fingerprints = %#v, want %#v", got, wantFingerprints)
 	}
@@ -46,7 +50,7 @@ func TestNormalizeNamesEvidenceAndIDs(t *testing.T) {
 			{SourceID: "b", StartUnitID: 2, EndUnitID: 3},
 		},
 	}}}
-	result, err := New(Options{}).Normalize(context.Background(), normalizeRequest(input))
+	result, err := newNormalizer(t, &recordingNPCNormalizerClient{}).Normalize(context.Background(), normalizeRequest(input))
 	if err != nil {
 		t.Fatalf("Normalize() error = %v", err)
 	}
@@ -68,7 +72,7 @@ func TestNormalizeOrdersEvidenceBySourceDocumentPosition(t *testing.T) {
 		{SourceID: doc.ID, StartUnitID: 30, EndUnitID: 30},
 		{SourceID: doc.ID, StartUnitID: 999, EndUnitID: 999},
 	}}}}
-	result, err := New(Options{}).Normalize(context.Background(), normalizeRequestWithSource(input, doc))
+	result, err := newNormalizer(t, &recordingNPCNormalizerClient{}).Normalize(context.Background(), normalizeRequestWithSource(input, doc))
 	if err != nil {
 		t.Fatalf("Normalize() error = %v", err)
 	}
@@ -84,7 +88,7 @@ func TestNormalizeConsolidatesCanonicalNamesOnlyAndUnionsEvidence(t *testing.T)
 		{Name: "captain vale", SourceRefs: []source.SourceRef{{SourceID: "b", StartUnitID: 2, EndUnitID: 2}}},
 		{Name: "The Captain", SourceRefs: []source.SourceRef{{SourceID: "c", StartUnitID: 3, EndUnitID: 3}}},
 	}}
-	result, err := New(Options{}).Normalize(context.Background(), normalizeRequest(input))
+	result, err := newNormalizer(t, &recordingNPCNormalizerClient{}).Normalize(context.Background(), normalizeRequest(input))
 	if err != nil {
 		t.Fatalf("Normalize() error = %v", err)
 	}
@@ -102,7 +106,7 @@ func TestNormalizeConsolidatesCanonicalNamesOnlyAndUnionsEvidence(t *testing.T)
 func TestNormalizePreservesInvalidCandidatesAndDoesNotAliasInput(t *testing.T) {
 	input := dnd.NPCList{NPCs: []dnd.NPC{{Name: " ", SourceRefs: []source.SourceRef{{SourceID: "source", StartUnitID: 0, EndUnitID: -1}}}}}
 	before := dnd.NPCList{NPCs: []dnd.NPC{{Name: " ", SourceRefs: []source.SourceRef{{SourceID: "source", StartUnitID: 0, EndUnitID: -1}}}}}
-	result, err := New(Options{}).Normalize(context.Background(), normalizeRequest(input))
+	result, err := newNormalizer(t, &recordingNPCNormalizerClient{}).Normalize(context.Background(), normalizeRequest(input))
 	if err != nil || !reflect.DeepEqual(input, before) {
 		t.Fatalf("Normalize() = %#v, %v; input mutated to %#v", result, err, input)
 	}
@@ -116,7 +120,7 @@ func TestNormalizePreservesInvalidCandidatesAndDoesNotAliasInput(t *testing.T) {
 }
 
 func TestNormalizeHandlesNilAndCanceledCalls(t *testing.T) {
-	normalizer := New(Options{})
+	normalizer := newNormalizer(t, &recordingNPCNormalizerClient{})
 	result, err := normalizer.Normalize(context.Background(), normalizeRequest(dnd.NPCList{NPCs: nil}))
 	if err != nil || result.Value.NPCs != nil {
 		t.Fatalf("nil list result = %#v, error = %v", result.Value, err)
@@ -128,6 +132,44 @@ func TestNormalizeHandlesNilAndCanceledCalls(t *testing.T) {
 	}
 }
 
+type recordingNPCNormalizerClient struct {
+	response  string
+	responses []string
+	err       error
+	requests  []contracts.StructuredCompletionRequest
+}
+
+func (c *recordingNPCNormalizerClient) CompleteStructured(_ context.Context, request contracts.StructuredCompletionRequest, output any) (contracts.StructuredCompletionResponse, error) {
+	c.requests = append(c.requests, request)
+	if c.err != nil {
+		return contracts.StructuredCompletionResponse{}, c.err
+	}
+	response := c.response
+	if len(c.responses) > 0 {
+		responseIndex := len(c.requests) - 1
+		if responseIndex >= len(c.responses) {
+			responseIndex = len(c.responses) - 1
+		}
+		response = c.responses[responseIndex]
+	}
+	if response == "" {
+		response = `{"duplicate_groups":[]}`
+	}
+	if err := json.Unmarshal([]byte(response), output); err != nil {
+		return contracts.StructuredCompletionResponse{}, err
+	}
+	return contracts.StructuredCompletionResponse{Content: json.RawMessage(response)}, nil
+}
+
+func newNormalizer(t *testing.T, client contracts.StructuredLLMClient) *Normalizer {
+	t.Helper()
+	normalizer, err := New(client, Options{})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	return normalizer
+}
+
 func normalizeRequest(value dnd.NPCList) contracts.TypedNormalizeRequest[dnd.NPCList] {
 	return contracts.TypedNormalizeRequest[dnd.NPCList]{MergeOutput: contracts.MergeArtifact[dnd.NPCList]{Value: value}}
 }