Migrate NPC and location normalization to native correction and explicit fallback handling
This commit is contained in:
@@ -15,23 +15,22 @@ import (
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/semanticreconcile"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
|
||||
registrycodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/locationregistry"
|
||||
"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"
|
||||
"go.maximumdirect.net/promptkit"
|
||||
)
|
||||
|
||||
const (
|
||||
Key = "dnd/location-registry"
|
||||
PromptID = "dnd.location_registry.normalize"
|
||||
PromptVersion = "v1"
|
||||
normalizationPolicy = "dnd.location_registry.normalize.v4"
|
||||
NormalizationPolicy = normalizationPolicy
|
||||
Key = "dnd/location-registry"
|
||||
PromptID = "notarius/dnd.location_registry.normalize"
|
||||
CorrectionPromptID = "notarius/dnd.location_registry.normalize.repair"
|
||||
|
||||
ReasonCodeLocationFieldsNormalized = "location_fields_normalized"
|
||||
ReasonCodeLocationIDRecomputed = "location_id_recomputed"
|
||||
ReasonCodeSourceReferencesNormalized = "source_references_normalized"
|
||||
ReasonCodeDuplicateLocationCollapsed = "duplicate_location_collapsed"
|
||||
ReasonCodeLocationSemanticProposalInvalid = "location_semantic_proposal_invalid"
|
||||
ReasonCodeLocationSemanticReconciliationExhausted = "location_semantic_reconciliation_exhausted"
|
||||
)
|
||||
|
||||
@@ -39,28 +38,16 @@ var requiredCapabilities = []string{"merged"}
|
||||
var providedCapabilities = []string{"normalized"}
|
||||
|
||||
var _ contracts.Normalizer[dnd.LocationRegistry] = (*Normalizer)(nil)
|
||||
var _ contracts.ManifestMetadataProvider = (*Normalizer)(nil)
|
||||
var _ pipeline.CheckpointFingerprintProvider = (*Normalizer)(nil)
|
||||
|
||||
type Options struct{}
|
||||
|
||||
type Normalizer struct {
|
||||
engine *semanticreconcile.Engine
|
||||
engine *promptkit.Engine
|
||||
}
|
||||
|
||||
func New(llmClient contracts.StructuredLLMClient, _ Options) (*Normalizer, error) {
|
||||
if llmClient == nil {
|
||||
return nil, normalizerErrorf("LLM client must not be nil")
|
||||
}
|
||||
promptSHA, err := promptAssetMetadata()
|
||||
if err != nil {
|
||||
return nil, normalizerErrorf("load prompt metadata: %w", err)
|
||||
}
|
||||
engine, err := semanticreconcile.NewEngine(llmClient, semanticreconcile.PromptSpec{
|
||||
ID: PromptID, Version: PromptVersion, SHA256: promptSHA,
|
||||
}, semanticreconcile.DefaultLimits())
|
||||
if err != nil {
|
||||
return nil, normalizerErrorf("construct semantic reconciliation engine: %w", err)
|
||||
func New(engine *promptkit.Engine, _ Options) (*Normalizer, error) {
|
||||
if engine == nil {
|
||||
return nil, normalizerErrorf("native engine must not be nil")
|
||||
}
|
||||
return &Normalizer{engine: engine}, nil
|
||||
}
|
||||
@@ -68,33 +55,12 @@ func New(llmClient contracts.StructuredLLMClient, _ Options) (*Normalizer, error
|
||||
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 || n.engine == nil {
|
||||
return nil
|
||||
}
|
||||
metadata := n.engine.ManifestMetadata()
|
||||
metadata["identity_policy"] = identity.Policy
|
||||
metadata["normalization_policy"] = normalizationPolicy
|
||||
return metadata
|
||||
}
|
||||
|
||||
func (n *Normalizer) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
|
||||
if n == nil || n.engine == nil {
|
||||
return nil
|
||||
}
|
||||
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.engine == nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("semantic reconciliation engine must not be nil")
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("native engine must not be nil")
|
||||
}
|
||||
if ctx == nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("context must not be nil")
|
||||
@@ -106,68 +72,139 @@ func (n *Normalizer) Normalize(ctx context.Context, req contracts.TypedNormalize
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("source document must not be nil")
|
||||
}
|
||||
|
||||
// Keep the already available merged artifact separate from preprocessed
|
||||
// originals. A failed native response must not recover an earlier proposal.
|
||||
merged := cloneRegistry(req.MergeOutput.Value)
|
||||
order := shared.NewSourceRefOrder(req.Source)
|
||||
records, findings := preprocessRecords(req.MergeOutput.Value, order)
|
||||
records, baseFindings := preprocessRecords(merged, order)
|
||||
deterministic := recordList(records)
|
||||
if len(records) < 2 {
|
||||
return normalizationResult(deterministic, findings, nil)
|
||||
}
|
||||
findings := append([]diagnostics.Finding(nil), baseFindings...)
|
||||
discardedGroups := -1
|
||||
var omissionDetails []string
|
||||
|
||||
fallback := func(_ context.Context, final *dnd.LocationRegistry) (dnd.LocationRegistry, error) {
|
||||
value := cloneRegistry(merged)
|
||||
if final != nil {
|
||||
// Each interpreted candidate was built afresh from fixed original records,
|
||||
// using only the final proposal's compatible, non-overlapping safe groups.
|
||||
value = cloneRegistry(*final)
|
||||
} else {
|
||||
findings = nil
|
||||
discardedGroups = -1
|
||||
omissionDetails = nil
|
||||
}
|
||||
if err := validateFallback(value, req.Source); err != nil {
|
||||
return dnd.LocationRegistry{}, err
|
||||
}
|
||||
return value, nil
|
||||
}
|
||||
finish := func(value dnd.LocationRegistry, outcome contracts.ProducerOutcome, err error) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("normalize locations: %w", err)
|
||||
}
|
||||
result, err := normalizationResult(value, findings)
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, err
|
||||
}
|
||||
result.Outcome = outcome
|
||||
if outcome.Disposition == contracts.ProducerFallback {
|
||||
details := append([]string(nil), omissionDetails...)
|
||||
details = append(details, outcome.FallbackReason)
|
||||
groups, err := diagnostics.Collect([]diagnostics.Finding{semanticFallbackFinding(discardedGroups, details...)}, contracts.DiagnosticDispositionWarning, contracts.DiagnosticCategoryFallback)
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("collect fallback diagnostic: %w", err)
|
||||
}
|
||||
result.Diagnostics = append(result.Diagnostics, groups...)
|
||||
}
|
||||
return result, nil
|
||||
}
|
||||
noModel := func() (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
|
||||
value, outcome, err := pipeline.AssessProducer(ctx, req.Operation, deterministic, func(ctx context.Context) (dnd.LocationRegistry, error) { return fallback(ctx, nil) })
|
||||
return finish(value, outcome, err)
|
||||
}
|
||||
if len(records) < 2 {
|
||||
return noModel()
|
||||
}
|
||||
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, StructuredOutputRepairAttempts: req.StructuredOutputRepairAttempts, Correction: req.Correction,
|
||||
})
|
||||
preparation, err := semanticreconcile.Prepare(req.Source, candidates, semanticreconcile.DefaultLimits())
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("reconcile semantic duplicates: %w", err)
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("prepare semantic reconciliation: %w", err)
|
||||
}
|
||||
|
||||
switch reconciliation.Disposition() {
|
||||
case semanticreconcile.SkippedInsufficientCandidates:
|
||||
return normalizationResult(deterministic, findings, nil)
|
||||
case semanticreconcile.SkippedLimitExceeded:
|
||||
return fallbackResult(deterministic, findings, semanticFallbackFinding(-1, "the candidate set exceeded the configured semantic-reconciliation limits"))
|
||||
case semanticreconcile.RetryableInvalidStructuredOutput:
|
||||
return n.invalidStructuredResult(deterministic, findings)
|
||||
case semanticreconcile.Complete, semanticreconcile.RetryableDiscardedProposalGroups:
|
||||
default:
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("unknown semantic reconciliation disposition %d", reconciliation.Disposition())
|
||||
switch preparation.Disposition() {
|
||||
case semanticreconcile.InsufficientCandidates:
|
||||
return noModel()
|
||||
case semanticreconcile.LimitExceeded:
|
||||
value, outcome, err := pipeline.FinishProducerFailure(ctx, req.Operation.Controls.Mode, normalizerErrorf("candidate set exceeded semantic reconciliation preparation limits"), func(ctx context.Context) (dnd.LocationRegistry, error) { return fallback(ctx, nil) })
|
||||
return finish(value, outcome, err)
|
||||
}
|
||||
|
||||
applied, semanticFindings, err := applyReconciliationPlan(reconciliation.Plan(), records, envelopes, order)
|
||||
initial, err := semanticreconcile.InitialRequest(preparation, PromptID, req.LLMProfile, req.SessionID)
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("apply semantic reconciliation plan: %w", err)
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("build native request: %w", err)
|
||||
}
|
||||
findings = append(findings, semanticFindings...)
|
||||
if reconciliation.Disposition() == semanticreconcile.Complete {
|
||||
return normalizationResult(recordList(applied), findings, reconciliation.ModelCandidate())
|
||||
}
|
||||
return retryResult(recordList(applied), findings, reconciliation)
|
||||
value, outcome, err := pipeline.RunProducer(ctx, n.engine, req.Operation, initial,
|
||||
func(_ context.Context, result *promptkit.RunResult) (*dnd.LocationRegistry, []string, error) {
|
||||
response, err := semanticreconcile.DecodeProposal(result.RawOutput)
|
||||
if err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
assessment := preparation.Assess(response)
|
||||
applied, semanticFindings, err := applyReconciliationPlan(assessment.Plan(), records, envelopes, order)
|
||||
if err != nil {
|
||||
return nil, nil, normalizerErrorf("apply semantic reconciliation plan: %w", err)
|
||||
}
|
||||
findings = append(append([]diagnostics.Finding(nil), baseFindings...), semanticFindings...)
|
||||
discardedGroups = assessment.DiscardedGroupCount()
|
||||
omissionDetails = semanticreconcile.IssueDetails(assessment.Issues())
|
||||
guidance, err := semanticreconcile.CorrectionDetails(assessment.Issues(), preparation.CandidateNumberRange())
|
||||
if err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
candidate := recordList(applied)
|
||||
return &candidate, guidance, nil
|
||||
},
|
||||
func(_ context.Context, guidance []string) (promptkit.RunRequest, error) {
|
||||
return semanticreconcile.CorrectionRequest(CorrectionPromptID, req.LLMProfile, req.SessionID, guidance), nil
|
||||
}, fallback)
|
||||
return finish(value, outcome, err)
|
||||
}
|
||||
|
||||
func (n *Normalizer) invalidStructuredResult(value dnd.LocationRegistry, findings []diagnostics.Finding) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
|
||||
return retryResultWithFallback(value, findings, nil, "", "semantic proposal requires retry: invalid structured output", semanticFallbackFinding(-1, "the final model response did not satisfy the structured-output contract"))
|
||||
// validateFallback checks the durable artifact and the identity/source invariants
|
||||
// used by registry consumers, not the configured ordinary validator chain.
|
||||
func validateFallback(value dnd.LocationRegistry, document *source.SourceDocument) error {
|
||||
if _, err := registrycodec.New().Encode(value); err != nil {
|
||||
return normalizerErrorf("construct locations fallback: %w", err)
|
||||
}
|
||||
if issues := identity.ValidateList(value); len(issues) > 0 {
|
||||
return normalizerErrorf("construct locations fallback: registry identity is not usable downstream")
|
||||
}
|
||||
index := source.NewDocumentIndex(document)
|
||||
for _, location := range value.Locations {
|
||||
for _, reference := range location.SourceRefs {
|
||||
if err := index.ValidateRef(reference); err != nil {
|
||||
return normalizerErrorf("construct locations fallback: %w", err)
|
||||
}
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func retryResult(value dnd.LocationRegistry, findings []diagnostics.Finding, reconciliation semanticreconcile.Result) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
|
||||
issues := reconciliation.Issues()
|
||||
correctionDetails, err := reconciliation.CorrectionDetails()
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("build semantic correction details: %w", err)
|
||||
func cloneRegistry(value dnd.LocationRegistry) dnd.LocationRegistry {
|
||||
if value.Locations == nil {
|
||||
return dnd.LocationRegistry{}
|
||||
}
|
||||
correctionGuidance, err := reconciliation.CorrectionGuidance()
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("build semantic correction guidance: %w", err)
|
||||
result := dnd.LocationRegistry{Locations: make([]dnd.Location, len(value.Locations))}
|
||||
for i, location := range value.Locations {
|
||||
result.Locations[i] = cloneLocation(location)
|
||||
}
|
||||
return retryResultWithFallback(value, findings, reconciliation.ModelCandidate(), correctionGuidance, diagnostics.Aggregate("semantic proposal requires retry", semanticreconcile.IssueDetails(issues)), semanticFallbackFinding(reconciliation.DiscardedGroupCount(), correctionDetails...))
|
||||
return result
|
||||
}
|
||||
|
||||
func semanticFallbackFinding(discarded int, details ...string) diagnostics.Finding {
|
||||
message := "semantic reconciliation could not be completed; all affected candidates were preserved separately"
|
||||
if discarded >= 0 {
|
||||
message := "semantic reconciliation did not obtain ordinary acceptance; using supported fallback output"
|
||||
if discarded > 0 {
|
||||
message = fmt.Sprintf("%d proposal group(s) omitted from the final semantic proposal; all affected candidates were preserved separately", discarded)
|
||||
}
|
||||
if len(details) > 0 {
|
||||
@@ -176,38 +213,12 @@ func semanticFallbackFinding(discarded int, details ...string) diagnostics.Findi
|
||||
return diagnostics.Finding{Scope: "locations", ReasonCode: ReasonCodeLocationSemanticReconciliationExhausted, Message: message}
|
||||
}
|
||||
|
||||
func normalizationResult(value dnd.LocationRegistry, findings []diagnostics.Finding, candidate *contracts.ModelCandidate) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
|
||||
diagnosticGroups, err := diagnostics.Collect(findings, contracts.DiagnosticDispositionObservation, contracts.DiagnosticCategoryNormalization)
|
||||
func normalizationResult(value dnd.LocationRegistry, findings []diagnostics.Finding) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
|
||||
groups, err := diagnostics.Collect(findings, contracts.DiagnosticDispositionObservation, contracts.DiagnosticCategoryNormalization)
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("collect normalization diagnostics: %w", err)
|
||||
}
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{Value: value, Diagnostics: diagnosticGroups, ModelCandidate: candidate}, nil
|
||||
}
|
||||
|
||||
func fallbackResult(value dnd.LocationRegistry, findings []diagnostics.Finding, fallback diagnostics.Finding) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
|
||||
result, err := normalizationResult(value, findings, nil)
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, err
|
||||
}
|
||||
fallbackGroups, err := diagnostics.Collect([]diagnostics.Finding{fallback}, contracts.DiagnosticDispositionWarning, contracts.DiagnosticCategoryFallback)
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("collect fallback diagnostic: %w", err)
|
||||
}
|
||||
result.Diagnostics = append(result.Diagnostics, fallbackGroups...)
|
||||
return result, nil
|
||||
}
|
||||
|
||||
func retryResultWithFallback(value dnd.LocationRegistry, findings []diagnostics.Finding, candidate *contracts.ModelCandidate, correctionGuidance, message string, fallback diagnostics.Finding) (contracts.TypedNormalizeResult[dnd.LocationRegistry], error) {
|
||||
result, err := normalizationResult(value, findings, candidate)
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, err
|
||||
}
|
||||
fallbackGroups, err := diagnostics.Collect([]diagnostics.Finding{fallback}, contracts.DiagnosticDispositionWarning, contracts.DiagnosticCategoryFallback)
|
||||
if err != nil {
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{}, normalizerErrorf("collect fallback diagnostic: %w", err)
|
||||
}
|
||||
result.Retry = &contracts.NormalizeRetry{ReasonCode: ReasonCodeLocationSemanticProposalInvalid, Message: message, CorrectionGuidance: correctionGuidance, FallbackDiagnostics: fallbackGroups}
|
||||
return result, nil
|
||||
return contracts.TypedNormalizeResult[dnd.LocationRegistry]{Value: value, Diagnostics: groups}, nil
|
||||
}
|
||||
|
||||
type normalizedRecord struct {
|
||||
@@ -373,7 +384,7 @@ func duplicateFinding(retainedIndex int, removed []int) diagnostics.Finding {
|
||||
func locationScope(index int) string { return fmt.Sprintf("locations[%d]", index) }
|
||||
|
||||
func ModuleSpec() pipeline.ModuleSpec {
|
||||
return pipeline.ModuleSpec{Key: Key, Stage: pipeline.StageNormalize, ExecutionClass: contracts.ExecutionClassLLMBacked, CorrectionProtocol: contracts.CorrectionProtocolSingleResponseV1, Requires: append([]string(nil), requiredCapabilities...), Provides: append([]string(nil), providedCapabilities...), ArtifactKind: dnd.LocationRegistryKind}
|
||||
return pipeline.ModuleSpec{Key: Key, Stage: pipeline.StageNormalize, ExecutionClass: contracts.ExecutionClassLLMBacked, Prompts: []string{PromptID, CorrectionPromptID}, Requires: append([]string(nil), requiredCapabilities...), Provides: append([]string(nil), providedCapabilities...), ArtifactKind: dnd.LocationRegistryKind}
|
||||
}
|
||||
func Register(registry *pipeline.NormalizerRegistry) error {
|
||||
return pipeline.RegisterNormalizerBuilder(registry, ModuleSpec(), validateOptions, func(request pipeline.BuildRequest) (contracts.Normalizer[dnd.LocationRegistry], error) {
|
||||
@@ -381,7 +392,7 @@ func Register(registry *pipeline.NormalizerRegistry) error {
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return New(request.Dependencies.LLM, options)
|
||||
return New(request.Dependencies.Engine, options)
|
||||
})
|
||||
}
|
||||
func validateOptions(options map[string]any) error { _, err := DecodeOptions(options); return err }
|
||||
|
||||
Reference in New Issue
Block a user