From d24d4609b697da12329e673614407c64eb237df3 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 9 Aug 2026 16:51:29 +0000 Subject: [PATCH] Migrate location reconciliation to shared engine --- .../normalize/prompts/candidates.md | 2 - .../normalize/prompts/instructions.md | 9 +- .../normalize/prompts/prompt.yaml | 10 +- .../normalize/locationregistry/normalizer.go | 114 ++++++++------- .../locationregistry/normalizer_test.go | 80 +++++++++-- .../locationregistry/prompt_assets.go | 36 +++-- .../locationregistry/prompt_assets_test.go | 8 +- .../locationregistry/reconciliation.go | 136 ++++++++---------- .../locationregistry/test_helpers_test.go | 45 +----- 9 files changed, 231 insertions(+), 209 deletions(-) delete mode 100644 assets/dnd/location-registry/normalize/prompts/candidates.md diff --git a/assets/dnd/location-registry/normalize/prompts/candidates.md b/assets/dnd/location-registry/normalize/prompts/candidates.md deleted file mode 100644 index 61c17ca..0000000 --- a/assets/dnd/location-registry/normalize/prompts/candidates.md +++ /dev/null @@ -1,2 +0,0 @@ -Location candidates: -{{ input "candidates" }} diff --git a/assets/dnd/location-registry/normalize/prompts/instructions.md b/assets/dnd/location-registry/normalize/prompts/instructions.md index 3042454..7575e96 100644 --- a/assets/dnd/location-registry/normalize/prompts/instructions.md +++ b/assets/dnd/location-registry/normalize/prompts/instructions.md @@ -1,6 +1,7 @@ -Use candidate names and their cited transcript windows to determine whether -candidates identify the same physical place. Do not treat matching names, -nearby evidence, nested places, or generic labels as sufficient. Keep parent -and child places, similarly named places, and uncertain aliases separate. +Use the supplied positive integer candidate IDs and their cited transcript +windows to determine whether candidates identify the same physical place. Do +not treat matching names, nearby evidence, nested places, or generic labels as +sufficient. Keep parent and child places, similarly named places, and uncertain +aliases separate. When selecting a canonical display name, prefer the clearest established name. diff --git a/assets/dnd/location-registry/normalize/prompts/prompt.yaml b/assets/dnd/location-registry/normalize/prompts/prompt.yaml index 8caca4f..b23d1b7 100644 --- a/assets/dnd/location-registry/normalize/prompts/prompt.yaml +++ b/assets/dnd/location-registry/normalize/prompts/prompt.yaml @@ -12,19 +12,19 @@ messages: - role: system content_file: ./sharedassets/common-dnd-system.md - role: user - content_file: ./instructions.md + content_file: ./sharedassets/protocol.md - role: user - content_file: ./sharedassets/common-dnd-entity-reconciliation.md + content_file: ./instructions.md cache_control: type: ephemeral - role: user - content_file: ./candidates.md + content_file: ./sharedassets/candidates.md - role: user - content_file: ./sharedassets/common-dnd-transcript-windows.md + content_file: ./sharedassets/transcript-windows.md cache_control: type: ephemeral output: format: json validation_mode: json_schema - schema_path: dnd_entity_reconcile_llm.v1.json + schema_path: semantic_reconciliation_llm.v1.json repair_attempts: 0 diff --git a/internal/modules/dnd/normalize/locationregistry/normalizer.go b/internal/modules/dnd/normalize/locationregistry/normalizer.go index 9eb8d41..ffbfc53 100644 --- a/internal/modules/dnd/normalize/locationregistry/normalizer.go +++ b/internal/modules/dnd/normalize/locationregistry/normalizer.go @@ -4,7 +4,6 @@ package locationregistry import ( "context" "encoding/json" - "errors" "fmt" "reflect" "sort" @@ -14,20 +13,19 @@ import ( "gitea.maximumdirect.net/eric/notarius/internal/core/source" "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" "gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline" + "gitea.maximumdirect.net/eric/notarius/internal/framework/semanticreconcile" "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd" "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/locations/identity" "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared" "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics" - "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/entityreconcile" ) const ( - Key = "dnd/location-registry" - PromptID = "dnd.location_registry.normalize" - normalizationPolicy = "dnd.location_registry.normalize.v2" - semanticContextPolicy = "dnd.entity_reconcile.context.v1" - semanticContextRadius = 2 - NormalizationPolicy = normalizationPolicy + Key = "dnd/location-registry" + PromptID = "dnd.location_registry.normalize" + PromptVersion = "v1" + normalizationPolicy = "dnd.location_registry.normalize.v3" + NormalizationPolicy = normalizationPolicy ReasonCodeLocationFieldsNormalized = "location_fields_normalized" ReasonCodeLocationIDRecomputed = "location_id_recomputed" @@ -48,9 +46,7 @@ var _ pipeline.CheckpointFingerprintProvider = (*Normalizer)(nil) type Options struct{} type Normalizer struct { - llm contracts.StructuredLLMClient - promptSHA string - responseSchemaSHA string + engine *semanticreconcile.Engine } func New(llmClient contracts.StructuredLLMClient, _ Options) (*Normalizer, error) { @@ -61,46 +57,45 @@ func New(llmClient contracts.StructuredLLMClient, _ Options) (*Normalizer, error if err != nil { return nil, normalizerErrorf("load prompt metadata: %w", err) } - responseSchema, err := entityreconcile.LoadResponseSchema() + engine, err := semanticreconcile.NewEngine(llmClient, semanticreconcile.PromptSpec{ + ID: PromptID, Version: PromptVersion, SHA256: promptSHA, + }, semanticreconcile.DefaultLimits()) if err != nil { - return nil, normalizerErrorf("load response schema: %w", err) + return nil, normalizerErrorf("construct semantic reconciliation engine: %w", err) } - return &Normalizer{llm: llmClient, promptSHA: promptSHA, responseSchemaSHA: responseSchema.SHA256}, nil + return &Normalizer{engine: engine}, nil } func (n *Normalizer) Key() string { return Key } func (n *Normalizer) ReferenceSlots() []contracts.ReferenceSlot { return nil } func (n *Normalizer) ManifestMetadata() map[string]any { - if n == nil { + if n == nil || n.engine == nil { return nil } - return map[string]any{ - "prompt_id": PromptID, "prompt_version": entityreconcile.SchemaVersion, "prompt_sha256": n.promptSHA, - "response_schema_key": string(entityreconcile.ResponseSchemaKey), "response_schema_id": entityreconcile.ResponseSchemaID, - "response_schema_name": entityreconcile.ResponseSchemaName, "response_schema_version": entityreconcile.SchemaVersion, - "response_schema_sha256": n.responseSchemaSHA, "identity_policy": identity.Policy, - "normalization_policy": normalizationPolicy, "semantic_context_policy": semanticContextPolicy, "semantic_context_radius": semanticContextRadius, - } + metadata := n.engine.ManifestMetadata() + metadata["identity_policy"] = identity.Policy + metadata["normalization_policy"] = normalizationPolicy + return metadata } func (n *Normalizer) CheckpointFingerprints() []pipeline.CheckpointFingerprint { - if n == nil { + if n == nil || n.engine == nil { return nil } - return []pipeline.CheckpointFingerprint{ - {Name: "prompt", Value: n.promptSHA}, {Name: "response_schema", Value: n.responseSchemaSHA}, - {Name: "identity_policy", Value: identity.Policy}, {Name: "normalization_policy", Value: normalizationPolicy}, - {Name: "semantic_context_policy", Value: fmt.Sprintf("%s:%d", semanticContextPolicy, semanticContextRadius)}, - } + fingerprints := n.engine.CheckpointFingerprints() + return append(fingerprints, + pipeline.CheckpointFingerprint{Name: "identity_policy", Value: identity.Policy}, + pipeline.CheckpointFingerprint{Name: "normalization_policy", Value: normalizationPolicy}, + ) } func (n *Normalizer) Normalize(ctx context.Context, req contracts.TypedNormalizeRequest[dnd.LocationRegistry]) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) { if n == nil { return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("normalizer must not be nil") } - if n.llm == nil { - return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("LLM client must not be nil") + if n.engine == nil { + return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("semantic reconciliation engine must not be nil") } if ctx == nil { return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("context must not be nil") @@ -112,32 +107,43 @@ func (n *Normalizer) Normalize(ctx context.Context, req contracts.TypedNormalize order := shared.NewSourceRefOrder(req.Source) records, warnings := preprocessRecords(req.MergeOutput.Value, order) deterministic := recordList(records) - materials, ready, err := entityreconcile.BuildContext(req.Source, reconciliationCandidates(records), semanticContextRadius) - if err != nil { - return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("build semantic context: %w", err) - } - if !ready { + if len(records) < 2 || req.Source == nil { return contracts.TypedNormalizeResult[dnd.LocationRegistry]{Value: deterministic, Warnings: limitWarnings(warnings)}, nil } - var response entityreconcile.ProposalResponse - if _, err := n.llm.CompleteStructured(ctx, contracts.StructuredCompletionRequest{ - StageName: Key, PromptID: PromptID, PromptVersion: entityreconcile.SchemaVersion, - ProfileID: req.LLMProfile, SessionID: req.SessionID, - Inputs: contracts.LLMInputSet{"candidates": materials.Candidates, "transcript": materials.Transcript}, - }, &response); err != nil { - if errors.Is(err, contracts.ErrInvalidStructuredOutput) { - return n.invalidStructuredResult(deterministic, warnings), nil - } - return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("complete structured output: %w", err) + candidates, envelopes, err := reconciliationInputs(records) + if err != nil { + return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("prepare semantic reconciliation inputs: %w", err) + } + reconciliation, err := n.engine.Reconcile(ctx, semanticreconcile.Request{ + StageName: Key, Source: req.Source, Candidates: candidates, + ProfileID: req.LLMProfile, SessionID: req.SessionID, + }) + if err != nil { + return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("reconcile semantic duplicates: %w", err) + } + + switch reconciliation.Disposition() { + case semanticreconcile.SkippedInsufficientCandidates: + return contracts.TypedNormalizeResult[dnd.LocationRegistry]{Value: deterministic, Warnings: limitWarnings(warnings)}, nil + case semanticreconcile.SkippedLimitExceeded: + return contracts.TypedNormalizeResult[dnd.LocationRegistry]{Value: deterministic, Warnings: limitWarningsWithSemanticFallback(warnings)}, nil + case semanticreconcile.RetryableInvalidStructuredOutput: + return n.invalidStructuredResult(deterministic, warnings), nil + case semanticreconcile.Complete, semanticreconcile.RetryableDiscardedProposalGroups: + default: + return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("unknown semantic reconciliation disposition %d", reconciliation.Disposition()) + } + + applied, semanticWarnings, err := applyReconciliationPlan(reconciliation.Plan(), records, envelopes, order) + if err != nil { + return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("apply semantic reconciliation plan: %w", err) } - assessment := materials.Assess(response) - applied, semanticWarnings := applySafeGroups(records, reconciliationGroups(assessment, materials.CandidateKeys()), order) warnings = append(warnings, semanticWarnings...) - if assessment.DiscardedGroups() == 0 { + if reconciliation.Disposition() == semanticreconcile.Complete { return contracts.TypedNormalizeResult[dnd.LocationRegistry]{Value: recordList(applied), Warnings: limitWarnings(warnings)}, nil } - return retryResult(recordList(applied), warnings, assessment), nil + return retryResult(recordList(applied), warnings, reconciliation), nil } func (n *Normalizer) invalidStructuredResult(value dnd.LocationRegistry, warnings []contracts.Warning) contracts.TypedNormalizeResult[dnd.LocationRegistry] { @@ -147,10 +153,10 @@ func (n *Normalizer) invalidStructuredResult(value dnd.LocationRegistry, warning }} } -func retryResult(value dnd.LocationRegistry, warnings []contracts.Warning, assessment entityreconcile.Assessment) contracts.TypedNormalizeResult[dnd.LocationRegistry] { +func retryResult(value dnd.LocationRegistry, warnings []contracts.Warning, reconciliation semanticreconcile.Result) contracts.TypedNormalizeResult[dnd.LocationRegistry] { return contracts.TypedNormalizeResult[dnd.LocationRegistry]{Value: value, Warnings: limitWarningsForRetry(warnings), Retry: &contracts.NormalizeRetry{ - ReasonCode: ReasonCodeLocationSemanticProposalInvalid, Message: diagnostics.Aggregate("semantic proposal requires retry", reconciliationIssues(assessment)), - FallbackWarnings: []contracts.Warning{semanticFallbackWarning(assessment.DiscardedGroups())}, + ReasonCode: ReasonCodeLocationSemanticProposalInvalid, Message: diagnostics.Aggregate("semantic proposal requires retry", reconciliationIssues(reconciliation.Issues())), + FallbackWarnings: []contracts.Warning{semanticFallbackWarning(reconciliation.DiscardedGroupCount())}, }} } @@ -178,6 +184,10 @@ func limitWarningsForRetry(warnings []contracts.Warning) []contracts.Warning { return append(bounded, contracts.Warning{Scope: "locations", ReasonCode: ReasonCodeLocationNormalizationWarningsOmitted, Message: fmt.Sprintf("%d additional warning(s) omitted", len(warnings)-displayed)}) } +func limitWarningsWithSemanticFallback(warnings []contracts.Warning) []contracts.Warning { + return append(limitWarningsForRetry(warnings), semanticFallbackWarning(-1)) +} + type normalizedRecord struct { location dnd.Location inputIndexes []int diff --git a/internal/modules/dnd/normalize/locationregistry/normalizer_test.go b/internal/modules/dnd/normalize/locationregistry/normalizer_test.go index 4263ccc..59db479 100644 --- a/internal/modules/dnd/normalize/locationregistry/normalizer_test.go +++ b/internal/modules/dnd/normalize/locationregistry/normalizer_test.go @@ -2,7 +2,9 @@ package locationregistry import ( "context" + "encoding/json" "errors" + "fmt" "reflect" "strconv" "strings" @@ -11,9 +13,10 @@ import ( "gitea.maximumdirect.net/eric/notarius/internal/core/source" "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" "gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline" + "gitea.maximumdirect.net/eric/notarius/internal/framework/semanticreconcile" "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd" "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/locations/identity" - "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/entityreconcile" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics" ) func TestModuleContractAndMetadata(t *testing.T) { @@ -30,11 +33,14 @@ func TestModuleContractAndMetadata(t *testing.T) { } normalizer := newNormalizer(t, &recordingLocationNormalizerClient{}) metadata := normalizer.ManifestMetadata() - if metadata["identity_policy"] != identity.Policy || metadata["response_schema_id"] != entityreconcile.ResponseSchemaID || metadata["normalization_policy"] != normalizationPolicy || metadata["semantic_context_radius"] != semanticContextRadius { + limits, ok := metadata["semantic_reconciliation_limits"].(map[string]any) + if !ok || metadata["identity_policy"] != identity.Policy || metadata["normalization_policy"] != normalizationPolicy || metadata["prompt_id"] != PromptID || metadata["prompt_version"] != PromptVersion || metadata["response_schema_key"] != string(semanticreconcile.ResponseSchemaKey) || metadata["response_schema_id"] != semanticreconcile.ResponseSchemaID || metadata["response_schema_name"] != semanticreconcile.ResponseSchemaName || metadata["semantic_reconciliation_policy"] != semanticreconcile.Policy || len(limits) != 3 { t.Fatalf("metadata = %#v", metadata) } - if got := normalizer.CheckpointFingerprints(); len(got) != 5 || got[2].Value != identity.Policy || got[3].Value != normalizationPolicy || got[4].Value != semanticContextPolicy+":2" { - t.Fatalf("fingerprints = %#v", got) + for _, name := range []string{"prompt", "response_schema", "semantic_reconciliation_policy", "semantic_reconciliation_limits", "identity_policy", "normalization_policy"} { + if !hasFingerprint(normalizer.CheckpointFingerprints(), name) { + t.Fatalf("fingerprints missing %q", name) + } } } @@ -46,7 +52,8 @@ func TestNormalizePreparesOnlyExactDuplicatesAndRetainsSameNameAndNestedPlaces(t {Name: "The Tavern Cellar", SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 2, EndUnitID: 2}}}, }} before := dnd.LocationRegistry{Locations: append([]dnd.Location(nil), input.Locations...)} - result, err := newNormalizer(t, &recordingLocationNormalizerClient{}).Normalize(context.Background(), normalizeRequest(input)) + client := &recordingLocationNormalizerClient{} + result, err := newNormalizer(t, client).Normalize(context.Background(), normalizeRequest(input)) if err != nil || len(result.Value.Locations) != 3 { t.Fatalf("Normalize() = %#v, %v; want one exact duplicate removed", result, err) } @@ -56,7 +63,7 @@ func TestNormalizePreparesOnlyExactDuplicatesAndRetainsSameNameAndNestedPlaces(t if got := []string{result.Value.Locations[0].Name, result.Value.Locations[1].Name, result.Value.Locations[2].Name}; !reflect.DeepEqual(got, []string{"The Tavern", "The Tavern", "The Tavern Cellar"}) { t.Fatalf("locations = %#v, want same names and nested place retained", got) } - if result.Value.Locations[0].ID == result.Value.Locations[1].ID || !hasWarning(result.Warnings, ReasonCodeDuplicateLocationCollapsed) { + if result.Value.Locations[0].ID == result.Value.Locations[1].ID || !hasWarning(result.Warnings, ReasonCodeDuplicateLocationCollapsed) || len(client.requests) != 0 { t.Fatalf("result = %#v, want evidence-anchored IDs and exact duplicate warning", result) } } @@ -79,7 +86,7 @@ func BenchmarkExactDuplicateGroupsManyDistinct(b *testing.B) { } func TestNormalizeAppliesSafeAliasGroupAndUsesContextualInputs(t *testing.T) { - client := &recordingLocationNormalizerClient{response: `{"duplicate_groups":[{"members":["candidate-000001","candidate-000002"],"canonical":"candidate-000002"}]}`} + client := &recordingLocationNormalizerClient{response: `{"duplicate_groups":[{"candidate_ids":[1,2],"canonical_candidate_id":2}]}`} doc := semanticDocument() input := dnd.LocationRegistry{Locations: []dnd.Location{ {Name: "Old Mill", SourceRefs: []source.SourceRef{{SourceID: doc.ID, StartUnitID: 10, EndUnitID: 10}}}, @@ -107,7 +114,7 @@ func TestNormalizeRejectsUnsafeAndOverlappingGroupsWithoutLosingCandidates(t *te {Name: "Mill", SourceRefs: []source.SourceRef{{SourceID: doc.ID, StartUnitID: 20, EndUnitID: 20}}}, {Name: "Tavern", SourceRefs: []source.SourceRef{{SourceID: doc.ID, StartUnitID: 30, EndUnitID: 30}}}, }} - client := &recordingLocationNormalizerClient{response: `{"duplicate_groups":[{"members":["candidate-000001","candidate-000002"],"canonical":"candidate-000001"},{"members":["candidate-000002","candidate-000003"],"canonical":"candidate-000003"}]}`} + client := &recordingLocationNormalizerClient{response: `{"duplicate_groups":[{"candidate_ids":[1,2],"canonical_candidate_id":1},{"candidate_ids":[2,3],"canonical_candidate_id":3}]}`} result, err := newNormalizer(t, client).Normalize(context.Background(), normalizeRequestWithSource(input, doc)) if err != nil || result.Retry == nil || len(result.Value.Locations) != 3 || !strings.Contains(result.Retry.Message, "overlapping_member") { t.Fatalf("Normalize() = %#v, %v; want safe retry fallback", result, err) @@ -117,6 +124,54 @@ func TestNormalizeRejectsUnsafeAndOverlappingGroupsWithoutLosingCandidates(t *te } } +func TestReconciliationCandidatesKeepSameNameEvidenceDistinct(t *testing.T) { + doc := semanticDocument() + records := []normalizedRecord{ + {location: dnd.Location{Name: "The Tavern", SourceRefs: []source.SourceRef{{SourceID: doc.ID, StartUnitID: 10, EndUnitID: 10}}}, inputIndexes: []int{0}, earliest: 0}, + {location: dnd.Location{Name: "The Tavern", SourceRefs: []source.SourceRef{{SourceID: doc.ID, StartUnitID: 30, EndUnitID: 30}}}, inputIndexes: []int{1}, earliest: 1}, + } + candidates, _, err := reconciliationInputs(records) + if err != nil { + t.Fatalf("reconciliationInputs() error = %v", err) + } + preparation, err := semanticreconcile.Prepare(doc, candidates, semanticreconcile.DefaultLimits()) + if err != nil || preparation.Disposition() != semanticreconcile.Ready { + t.Fatalf("Prepare() = %#v, %v; want ready candidates", preparation, err) + } + var candidateInput struct { + Candidates []struct { + CandidateID int `json:"candidate_id"` + Label string `json:"label"` + } `json:"candidates"` + } + if err := json.Unmarshal(preparation.Materials()["candidates"].Content, &candidateInput); err != nil { + t.Fatal(err) + } + if len(candidateInput.Candidates) != 2 || candidateInput.Candidates[0].CandidateID != 1 || candidateInput.Candidates[1].CandidateID != 2 || candidateInput.Candidates[0].Label != "The Tavern" || candidateInput.Candidates[1].Label != "The Tavern" { + t.Fatalf("candidate input = %#v, want distinct integer handles for equal names", candidateInput) + } +} + +func TestNormalizeLimitSkipDoesNotCallLLMAndAddsBoundedFallbackWarning(t *testing.T) { + client := &recordingLocationNormalizerClient{} + doc := &source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 1, Kind: "narration", Text: "A sprawling city"}}} + limit := semanticreconcile.DefaultLimits().MaximumCandidates + input := dnd.LocationRegistry{Locations: make([]dnd.Location, limit+1)} + for index := range input.Locations { + input.Locations[index] = dnd.Location{Name: fmt.Sprintf("Place %d", index), SourceRefs: []source.SourceRef{{SourceID: doc.ID, StartUnitID: 1, EndUnitID: 1}}} + } + result, err := newNormalizer(t, client).Normalize(context.Background(), normalizeRequestWithSource(input, doc)) + if err != nil || result.Retry != nil { + t.Fatalf("Normalize() = %#v, %v; want deterministic limit fallback", result, err) + } + if len(client.requests) != 0 || len(result.Value.Locations) != limit+1 { + t.Fatalf("completion calls = %d, locations = %d; want no call and all records", len(client.requests), len(result.Value.Locations)) + } + if !hasWarning(result.Warnings, ReasonCodeLocationSemanticReconciliationExhausted) || len(result.Warnings) > diagnostics.MaxWarnings { + t.Fatalf("warnings = %#v, want bounded reconciliation fallback", result.Warnings) + } +} + func TestNormalizeHandlesRetryFallbackAndErrors(t *testing.T) { doc := semanticDocument() input := dnd.LocationRegistry{Locations: []dnd.Location{{Name: "Old Mill", SourceRefs: []source.SourceRef{{SourceID: doc.ID, StartUnitID: 10, EndUnitID: 10}}}, {Name: "Mill", SourceRefs: []source.SourceRef{{SourceID: doc.ID, StartUnitID: 20, EndUnitID: 20}}}}} @@ -152,3 +207,12 @@ func TestNormalizeOrdersEvidenceAndIsIdempotent(t *testing.T) { t.Fatalf("second Normalize() = %#v, %v; want idempotent value %#v", second, err, first.Value) } } + +func hasFingerprint(fingerprints []pipeline.CheckpointFingerprint, name string) bool { + for _, fingerprint := range fingerprints { + if fingerprint.Name == name && fingerprint.Value != "" { + return true + } + } + return false +} diff --git a/internal/modules/dnd/normalize/locationregistry/prompt_assets.go b/internal/modules/dnd/normalize/locationregistry/prompt_assets.go index c9ccb8d..da11b2c 100644 --- a/internal/modules/dnd/normalize/locationregistry/prompt_assets.go +++ b/internal/modules/dnd/normalize/locationregistry/prompt_assets.go @@ -8,19 +8,26 @@ import ( rootassets "gitea.maximumdirect.net/eric/notarius/assets" "gitea.maximumdirect.net/eric/notarius/internal/framework/llm" "gitea.maximumdirect.net/eric/notarius/internal/framework/promptfs" + "gitea.maximumdirect.net/eric/notarius/internal/framework/semanticreconcile" "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared" ) const promptAssetRoot = "assets/prompts" -var promptAssetManifest = shared.PromptAssetManifest{ - ModuleDir: PromptID, - ModuleFiles: []promptfs.ModulePromptFile{ - {Name: "prompt.yaml", Path: "prompts/prompt.yaml"}, - {Name: "instructions.md", Path: "prompts/instructions.md"}, - {Name: "candidates.md", Path: "prompts/candidates.md"}, - }, - SharedFiles: []string{"common-dnd-system.md", "common-dnd-entity-reconciliation.md", "common-dnd-transcript-windows.md"}, +func promptAssetManifest() (shared.PromptAssetManifest, error) { + sharedFiles, err := semanticreconcile.SharedPromptFiles() + if err != nil { + return shared.PromptAssetManifest{}, fmt.Errorf("load shared semantic reconciliation prompt assets: %w", err) + } + return shared.PromptAssetManifest{ + ModuleDir: PromptID, + ModuleFiles: []promptfs.ModulePromptFile{ + {Name: "prompt.yaml", Path: "prompts/prompt.yaml"}, + {Name: "instructions.md", Path: "prompts/instructions.md"}, + }, + SharedFiles: []string{"common-dnd-system.md"}, + ExternalSharedFiles: sharedFiles, + }, nil } func moduleAssetFS() (fs.FS, error) { @@ -36,7 +43,11 @@ func RegisterPromptAssets(registry *llm.AssetRegistry) error { if err != nil { return err } - promptFS, err := promptAssetManifest.PromptFS(assets) + manifest, err := promptAssetManifest() + if err != nil { + return err + } + promptFS, err := manifest.PromptFS(assets) if err != nil { return fmt.Errorf("prepare location normalization prompt assets: %w", err) } @@ -50,7 +61,12 @@ func promptAssetMetadata() (string, error) { promptAssetHashErr = err return } - promptAssetHash, promptAssetHashErr = promptAssetManifest.Hash(assets) + manifest, err := promptAssetManifest() + if err != nil { + promptAssetHashErr = err + return + } + promptAssetHash, promptAssetHashErr = manifest.Hash(assets) }) return promptAssetHash, promptAssetHashErr } diff --git a/internal/modules/dnd/normalize/locationregistry/prompt_assets_test.go b/internal/modules/dnd/normalize/locationregistry/prompt_assets_test.go index 53ee279..ba54f9a 100644 --- a/internal/modules/dnd/normalize/locationregistry/prompt_assets_test.go +++ b/internal/modules/dnd/normalize/locationregistry/prompt_assets_test.go @@ -7,13 +7,13 @@ import ( "time" "gitea.maximumdirect.net/eric/notarius/internal/framework/llm" - "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/entityreconcile" + "gitea.maximumdirect.net/eric/notarius/internal/framework/semanticreconcile" "gitea.maximumdirect.net/eric/promptkit" ) func TestRegisterPromptAssetsPreparesLocationNormalizationPrompt(t *testing.T) { registry := llm.NewAssetRegistry() - if err := entityreconcile.RegisterSchemaAssets(registry); err != nil { + if err := semanticreconcile.RegisterAssets(registry); err != nil { t.Fatal(err) } if err := RegisterPromptAssets(registry); err != nil { @@ -28,11 +28,11 @@ func TestRegisterPromptAssetsPreparesLocationNormalizationPrompt(t *testing.T) { if err != nil { t.Fatal(err) } - prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{PromptID: PromptID, PromptVersion: entityreconcile.SchemaVersion, ProfileID: "location-normalize-test", Inputs: map[string]promptkit.ArtifactRef{"candidates": promptkit.Inline(`{"candidates":[{"name":"The Tavern","source_refs":[{"start_unit_id":1,"end_unit_id":1}]}]}`), "transcript": promptkit.Inline(`{"windows":[{"units":[]}]}`)}}) + prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{PromptID: PromptID, PromptVersion: PromptVersion, ProfileID: "location-normalize-test", Inputs: map[string]promptkit.ArtifactRef{"candidates": promptkit.Inline(`{"candidates":[{"candidate_id":1,"label":"The Tavern","source_refs":[{"start_unit_id":1,"end_unit_id":1}]}]}`), "transcript": promptkit.Inline(`{"windows":[{"units":[]}]}`)}}) if err != nil { t.Fatal(err) } - if prepared.OutputContract.SchemaPath != "dnd_entity_reconcile_llm.v1.json" { + if prepared.OutputContract.SchemaPath != "semantic_reconciliation_llm.v1.json" || !strings.Contains(prepared.Messages[1].Content, "candidate_id") || !strings.Contains(prepared.Messages[1].Content, "integer") || !strings.Contains(prepared.Messages[2].Content, "same physical place") || !strings.Contains(prepared.Messages[2].Content, "parent and child places") { t.Fatalf("prepared prompt = %#v", prepared) } for _, index := range []int{2, 4} { diff --git a/internal/modules/dnd/normalize/locationregistry/reconciliation.go b/internal/modules/dnd/normalize/locationregistry/reconciliation.go index 2f82243..24a10c7 100644 --- a/internal/modules/dnd/normalize/locationregistry/reconciliation.go +++ b/internal/modules/dnd/normalize/locationregistry/reconciliation.go @@ -4,54 +4,66 @@ import ( "fmt" "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" + "gitea.maximumdirect.net/eric/notarius/internal/framework/semanticreconcile" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd" "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/locations/identity" "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared" "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics" - "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/entityreconcile" ) -type safeReconciliationGroup struct { - members []int - canonical int -} - -func reconciliationCandidates(records []normalizedRecord) []entityreconcile.Candidate { - candidates := make([]entityreconcile.Candidate, len(records)) +func reconciliationInputs(records []normalizedRecord) ([]semanticreconcile.Candidate, []semanticreconcile.Record[dnd.Location], error) { + candidates := make([]semanticreconcile.Candidate, len(records)) + envelopes := make([]semanticreconcile.Record[dnd.Location], len(records)) for index, record := range records { - candidates[index] = entityreconcile.Candidate{Name: record.location.Name, SourceRefs: cloneSourceRefs(record.location.SourceRefs)} + candidates[index] = semanticreconcile.Candidate{ + Label: record.location.Name, + SourceRefs: cloneSourceRefs(record.location.SourceRefs), + } + envelope, err := semanticreconcile.NewRecord(record.location, record.inputIndexes, record.earliest, cloneLocation) + if err != nil { + return nil, nil, fmt.Errorf("record %d: %w", index, err) + } + envelopes[index] = envelope } - return candidates + return candidates, envelopes, nil } -func reconciliationGroups(assessment entityreconcile.Assessment, candidateKeys []string) []safeReconciliationGroup { - positions := make(map[string]int, len(candidateKeys)) - for index, key := range candidateKeys { - positions[key] = index - } - safeGroups := assessment.SafeGroups() - groups := make([]safeReconciliationGroup, 0, len(safeGroups)) - for _, group := range safeGroups { - members := group.Members() - memberPositions := make([]int, len(members)) - valid := true - for index, key := range members { - position, ok := positions[key] - if !ok { - valid = false - break +func applyReconciliationPlan(plan semanticreconcile.Plan, records []normalizedRecord, envelopes []semanticreconcile.Record[dnd.Location], order shared.SourceRefOrder) ([]normalizedRecord, []contracts.Warning, error) { + application, err := semanticreconcile.ApplyPlan(plan, envelopes, semanticreconcile.ApplicationPolicy[dnd.Location]{ + CloneValue: cloneLocation, + ConsolidateGroup: func(members []dnd.Location, canonical dnd.Location) (dnd.Location, error) { + output := cloneLocation(canonical) + output.SourceRefs = nil + for _, member := range members { + output.SourceRefs = append(output.SourceRefs, member.SourceRefs...) } - memberPositions[index] = position - } - canonical, ok := positions[group.Canonical()] - if valid && ok { - groups = append(groups, safeReconciliationGroup{members: memberPositions, canonical: canonical}) + output.SourceRefs = order.Canonicalize(output.SourceRefs) + output.ID = identity.DeriveID(output.Name, output.SourceRefs) + return output, nil + }, + }) + if err != nil { + return nil, nil, err + } + + applied := application.Records() + output := make([]normalizedRecord, len(applied)) + for index, record := range applied { + output[index] = normalizedRecord{ + location: record.Value(), + inputIndexes: record.OriginalInputIndexes(), + earliest: record.EarliestInputPosition(), } } - return groups + warnings := make([]contracts.Warning, 0, len(application.AppliedGroups())) + for _, event := range application.AppliedGroups() { + provenance := event.Provenance() + warnings = append(warnings, semanticDuplicateWarning(provenance, records[provenance.CanonicalPosition()])) + } + return output, warnings, nil } -func reconciliationIssues(assessment entityreconcile.Assessment) []string { - issues := assessment.Issues() +func reconciliationIssues(issues []semanticreconcile.Issue) []string { details := make([]string, len(issues)) for index, issue := range issues { details[index] = fmt.Sprintf("group %d: %s", issue.GroupIndex, issue.Category) @@ -59,54 +71,18 @@ func reconciliationIssues(assessment entityreconcile.Assessment) []string { return details } -func applySafeGroups(records []normalizedRecord, groups []safeReconciliationGroup, order shared.SourceRefOrder) ([]normalizedRecord, []contracts.Warning) { - byMember := make(map[int]safeReconciliationGroup, len(groups)*2) - for _, group := range groups { - for _, member := range group.members { - byMember[member] = group - } - } - output := make([]normalizedRecord, 0, len(records)-len(groups)) - warnings := make([]contracts.Warning, 0, len(groups)) - for index, record := range records { - group, grouped := byMember[index] - if !grouped { - output = append(output, cloneRecord(record)) - continue - } - if group.members[0] != index { - continue - } - consolidated := consolidateSemanticGroup(records, group, order) - output = append(output, consolidated) - warnings = append(warnings, semanticDuplicateWarning(consolidated, records[group.canonical])) - } - return output, warnings -} - -func consolidateSemanticGroup(records []normalizedRecord, group safeReconciliationGroup, order shared.SourceRefOrder) normalizedRecord { - output := cloneRecord(records[group.members[0]]) - output.location.Name = records[group.canonical].location.Name - for _, member := range group.members[1:] { - output.location.SourceRefs = append(output.location.SourceRefs, records[member].location.SourceRefs...) - output.inputIndexes = append(output.inputIndexes, records[member].inputIndexes...) - if records[member].earliest < output.earliest { - output.earliest = records[member].earliest - } - } - output.inputIndexes = sortedUniqueIndexes(output.inputIndexes) - output.location.SourceRefs = order.Canonicalize(output.location.SourceRefs) - output.location.ID = identity.DeriveID(output.location.Name, output.location.SourceRefs) - return output -} - -func semanticDuplicateWarning(record normalizedRecord, canonical normalizedRecord) contracts.Warning { - details := make([]string, 0, len(record.inputIndexes)+1) - for _, inputIndex := range record.inputIndexes { +func semanticDuplicateWarning(provenance semanticreconcile.GroupProvenance, canonical normalizedRecord) contracts.Warning { + inputIndexes := provenance.OriginalInputIndexes() + details := make([]string, 0, len(inputIndexes)+1) + for _, inputIndex := range inputIndexes { details = append(details, fmt.Sprintf("input index %d", inputIndex)) } - if canonical.earliest != record.earliest { + if canonical.earliest != provenance.EarliestInputPosition() { details = append(details, fmt.Sprintf("canonical display name from input index %d", canonical.earliest)) } - return contracts.Warning{Scope: locationScope(record.earliest), ReasonCode: ReasonCodeDuplicateLocationCollapsed, Message: diagnostics.Aggregate("semantic duplicate consolidation", details)} + return contracts.Warning{ + Scope: locationScope(provenance.EarliestInputPosition()), + ReasonCode: ReasonCodeDuplicateLocationCollapsed, + Message: diagnostics.Aggregate("semantic duplicate consolidation", details), + } } diff --git a/internal/modules/dnd/normalize/locationregistry/test_helpers_test.go b/internal/modules/dnd/normalize/locationregistry/test_helpers_test.go index 6a8e835..0d4a54b 100644 --- a/internal/modules/dnd/normalize/locationregistry/test_helpers_test.go +++ b/internal/modules/dnd/normalize/locationregistry/test_helpers_test.go @@ -3,14 +3,11 @@ package locationregistry import ( "context" "encoding/json" - "strconv" - "strings" "testing" "gitea.maximumdirect.net/eric/notarius/internal/core/source" "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd" - "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/entityreconcile" ) type recordingLocationNormalizerClient struct { @@ -28,53 +25,13 @@ func (c *recordingLocationNormalizerClient) CompleteStructured(_ context.Context if response == "" { response = `{"duplicate_groups":[]}` } - content, err := contextualProposalResponse(response, request.Inputs["candidates"].Content) - if err != nil { - return contracts.StructuredCompletionResponse{}, err - } + content := []byte(response) if err := json.Unmarshal(content, output); err != nil { return contracts.StructuredCompletionResponse{}, err } return contracts.StructuredCompletionResponse{Content: content}, nil } -func contextualProposalResponse(response string, candidateContent []byte) ([]byte, error) { - if !strings.Contains(response, "candidate-") { - return []byte(response), nil - } - var selection struct { - DuplicateGroups []struct { - Members []string `json:"members"` - Canonical string `json:"canonical"` - } `json:"duplicate_groups"` - } - if err := json.Unmarshal([]byte(response), &selection); err != nil { - return nil, err - } - var candidates struct { - Candidates []entityreconcile.Selector `json:"candidates"` - } - if err := json.Unmarshal(candidateContent, &candidates); err != nil { - return nil, err - } - selector := func(key string) entityreconcile.Selector { - index, err := strconv.Atoi(strings.TrimPrefix(key, "candidate-")) - if err != nil || index < 1 || index > len(candidates.Candidates) { - return entityreconcile.Selector{Name: key, SourceRefs: []entityreconcile.SourceRange{}} - } - return candidates.Candidates[index-1].Clone() - } - proposal := entityreconcile.ProposalResponse{DuplicateGroups: make([]entityreconcile.DuplicateGroup, len(selection.DuplicateGroups))} - for index, group := range selection.DuplicateGroups { - members := make([]entityreconcile.Selector, len(group.Members)) - for memberIndex, key := range group.Members { - members[memberIndex] = selector(key) - } - proposal.DuplicateGroups[index] = entityreconcile.DuplicateGroup{Members: members, Canonical: selector(group.Canonical)} - } - return json.Marshal(proposal) -} - func newNormalizer(t *testing.T, client contracts.StructuredLLMClient) *Normalizer { t.Helper() normalizer, err := New(client, Options{})