2026-08-04 00:18:16 +00:00
// Package locationoccurrences extracts source-grounded D&D location occurrences.
package locationoccurrences
import (
"context"
2026-11-22 01:03:06 +00:00
"encoding/json"
2026-08-04 00:18:16 +00:00
"fmt"
"sort"
2026-11-22 01:03:06 +00:00
"strings"
"go.maximumdirect.net/promptkit"
2026-08-04 00:18:16 +00:00
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
locationregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/locations/registry"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
)
2026-11-22 01:03:06 +00:00
const Key = "dnd/location-occurrences"
const PromptID = "notarius/dnd.location_occurrences"
const CorrectionPromptID = "notarius/dnd.location_occurrences.repair"
2026-08-04 00:18:16 +00:00
const (
LocationRegistryReferenceSlot = locationregistry . ReferenceSlot
LocationRegistryMaxBytes = locationregistry . MaxBytes
)
var requiredCapabilities = [ ] string { "chunks" , "source.transcript" }
var providedCapabilities = [ ] string { "dnd.location_occurrences" }
var referenceSlotDescriptions = shared . ReferenceSlotDescriptions {
Glossary : "Optional campaign glossary reference material used only for location-occurrence disambiguation." ,
Party : "Optional party roster reference material used only for location-occurrence disambiguation." ,
Players : "Optional player list reference material used only for location-occurrence disambiguation." ,
Roster : "Deprecated alias for party roster reference material used only for location-occurrence disambiguation." ,
}
func referenceSlots ( ) [ ] contracts . ReferenceSlot {
slots := shared . ReferenceSlots ( referenceSlotDescriptions )
slots = append ( slots , contracts . ReferenceSlot {
Name : LocationRegistryReferenceSlot ,
Description : "Required normalized location registry used only for location identity grounding, never as occurrence evidence." ,
Required : true ,
AcceptedMediaTypes : [ ] string { "application/json" } ,
2026-08-05 19:05:42 +00:00
AcceptedArtifactKinds : [ ] contracts . ArtifactKind { dnd . LocationRegistryKind } ,
2026-08-04 00:18:16 +00:00
MaxBytes : LocationRegistryMaxBytes ,
} )
sort . Slice ( slots , func ( left , right int ) bool { return slots [ left ] . Name < slots [ right ] . Name } )
return slots
}
var _ contracts . Extractor [ dnd . LocationOccurrenceList ] = ( * Extractor ) ( nil )
type Options struct { }
type Extractor struct {
2026-11-22 01:03:06 +00:00
engine * promptkit . Engine
locationResolver * locationregistry . Resolver
2026-08-04 00:18:16 +00:00
}
2026-11-22 01:03:06 +00:00
func New ( engine * promptkit . Engine , _ Options , references ... contracts . ReferenceSet ) ( * Extractor , error ) {
if engine == nil {
return nil , extractorErrorf ( "native engine must not be nil" )
2026-08-04 00:18:16 +00:00
}
if len ( references ) > 1 {
return nil , extractorErrorf ( "at most one reference set may be supplied" )
}
var referenceSet contracts . ReferenceSet
if len ( references ) == 1 {
referenceSet = references [ 0 ]
}
locationResolver , err := locationregistry . NewResolver ( referenceSet )
if err != nil {
return nil , extractorErrorf ( "prepare location registry prompt input: %w" , err )
}
2026-11-22 01:03:06 +00:00
return & Extractor { engine : engine , locationResolver : locationResolver } , nil
2026-08-04 00:18:16 +00:00
}
func ( e * Extractor ) Key ( ) string { return Key }
func ( e * Extractor ) ReferenceSlots ( ) [ ] contracts . ReferenceSlot { return referenceSlots ( ) }
2026-11-22 01:03:06 +00:00
func ( e * Extractor ) Extract ( ctx context . Context , req contracts . TypedExtractionRequest [ dnd . LocationOccurrenceList ] ) ( contracts . TypedExtractionResult [ dnd . LocationOccurrenceList ] , error ) {
2026-08-04 00:18:16 +00:00
if e == nil {
return contracts . TypedExtractionResult [ dnd . LocationOccurrenceList ] { } , extractorErrorf ( "extractor must not be nil" )
}
2026-11-22 01:03:06 +00:00
if e . engine == nil {
return contracts . TypedExtractionResult [ dnd . LocationOccurrenceList ] { } , extractorErrorf ( "native engine must not be nil" )
2026-08-04 00:18:16 +00:00
}
sourceInput , err := shared . PrepareChunkExtraction ( ctx , req )
if err != nil {
return contracts . TypedExtractionResult [ dnd . LocationOccurrenceList ] { } , extractorErrorf ( "%w" , err )
}
registry , err := e . locationResolver . Resolve ( req . References )
if err != nil {
return contracts . TypedExtractionResult [ dnd . LocationOccurrenceList ] { } , extractorErrorf ( "resolve location registry: %w" , err )
}
if ! registry . Bound ( ) {
return contracts . TypedExtractionResult [ dnd . LocationOccurrenceList ] { } , extractorErrorf ( "location registry reference is required" )
}
2026-08-08 14:56:43 +00:00
grounding , err := locationregistry . NewGrounding ( registry , req . Source )
if err != nil {
return contracts . TypedExtractionResult [ dnd . LocationOccurrenceList ] { } , extractorErrorf ( "prepare location grounding: %w" , err )
}
2026-08-04 00:18:16 +00:00
2026-11-22 01:03:06 +00:00
order := shared . NewSourceRefOrder ( req . Source )
sourceID := req . Source . ID
materials := shared . PromptInputs ( sourceInput , req . References )
materials [ LocationRegistryReferenceSlot ] = grounding . PromptInput ( )
inputs := make ( map [ string ] promptkit . ArtifactRef , len ( materials ) )
for name , material := range materials {
inputs [ name ] = promptkit . InlineWithURI ( material . OriginURI , string ( material . Content ) )
}
initial := promptkit . RunRequest { PromptID : PromptID , ProfileID : req . LLMProfile , SessionID : req . SessionID , Inputs : inputs }
value , outcome , err := pipeline . RunProducer ( ctx , e . engine , req . Operation , initial ,
func ( _ context . Context , result * promptkit . RunResult ) ( * dnd . LocationOccurrenceList , [ ] string , error ) {
var response extractionResponse
if err := json . Unmarshal ( [ ] byte ( result . RawOutput ) , & response ) ; err != nil {
return nil , nil , extractorErrorf ( "decode native output: %w" , err )
}
value , err := canonicalOccurrenceList ( response , order , sourceID , grounding )
if err != nil {
return nil , [ ] string { "Resolve every occurrence to exactly one supplied location selector. Copy its canonical name and complete ordered registry_refs array; use an empty registry_refs array for a unique name. Omit unsupported or ambiguous selections. Keep occurrence evidence in source_refs separate from registry context, and return the complete replacement occurrence list." } , nil
}
return & value , nil , nil
} ,
func ( _ context . Context , guidance [ ] string ) ( promptkit . RunRequest , error ) {
return promptkit . RunRequest { PromptID : CorrectionPromptID , ProfileID : req . LLMProfile , SessionID : req . SessionID ,
Inputs : map [ string ] promptkit . ArtifactRef { "guidance" : promptkit . Inline ( strings . Join ( guidance , "\n\n" ) ) } } , nil
} ,
func ( context . Context , * dnd . LocationOccurrenceList ) ( dnd . LocationOccurrenceList , error ) {
return dnd . LocationOccurrenceList { Occurrences : [ ] dnd . LocationOccurrence { } } , nil
} )
2026-08-08 14:56:43 +00:00
if err != nil {
2026-11-22 01:03:06 +00:00
return contracts . TypedExtractionResult [ dnd . LocationOccurrenceList ] { } , extractorErrorf ( "produce occurrences: %w" , err )
2026-08-08 14:56:43 +00:00
}
2026-11-22 01:03:06 +00:00
return contracts . TypedExtractionResult [ dnd . LocationOccurrenceList ] { Value : value , Outcome : outcome } , nil
2026-08-04 00:18:16 +00:00
}
func ModuleSpec ( ) pipeline . ModuleSpec {
return pipeline . ModuleSpec {
Key : Key , Stage : pipeline . StageExtract , ExecutionClass : contracts . ExecutionClassLLMBacked ,
2026-11-22 01:03:06 +00:00
Prompts : [ ] string { PromptID , CorrectionPromptID } ,
Requires : append ( [ ] string ( nil ) , requiredCapabilities ... ) , Provides : append ( [ ] string ( nil ) , providedCapabilities ... ) ,
2026-08-04 00:18:16 +00:00
ArtifactKind : dnd . LocationOccurrenceListKind , ReferenceSlots : referenceSlots ( ) ,
}
}
func Register ( registry * pipeline . ExtractorRegistry ) error {
return pipeline . RegisterExtractorBuilder ( registry , ModuleSpec ( ) , validateOptions , func ( request pipeline . BuildRequest ) ( contracts . Extractor [ dnd . LocationOccurrenceList ] , error ) {
options , err := DecodeOptions ( request . Options )
if err != nil {
return nil , err
}
2026-11-22 01:03:06 +00:00
return New ( request . Dependencies . Engine , options , request . References )
2026-08-04 00:18:16 +00:00
} )
}
func validateOptions ( options map [ string ] any ) error { _ , err := DecodeOptions ( options ) ; return err }
func DecodeOptions ( options map [ string ] any ) ( Options , error ) {
if err := pipeline . RejectUnknownOptions ( options ) ; err != nil {
return Options { } , extractorErrorf ( "%w" , err )
}
return Options { } , nil
}
func extractorErrorf ( format string , args ... any ) error {
return fmt . Errorf ( "dnd location occurrences extractor: " + format , args ... )
}