2026-08-05 19:00:55 +00:00
package npcoccurrences
2026-07-23 13:26:27 +00:00
import (
"context"
2026-11-22 01:03:06 +00:00
"encoding/json"
2026-07-23 13:26:27 +00:00
"fmt"
"sort"
2026-11-22 01:03:06 +00:00
"strings"
"go.maximumdirect.net/promptkit"
2026-07-23 13:26:27 +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"
npcregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/registry"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
)
2026-11-22 01:03:06 +00:00
const Key = "dnd/npc-occurrences"
const PromptID = "notarius/dnd.npc_occurrences"
const CorrectionPromptID = "notarius/dnd.npc_occurrences.repair"
2026-07-23 13:26:27 +00:00
const (
NPCRegistryReferenceSlot = npcregistry . ReferenceSlot
NPCRegistryMaxBytes = npcregistry . MaxBytes
)
var requiredCapabilities = [ ] string {
"chunks" ,
"source.transcript" ,
}
var providedCapabilities = [ ] string {
2026-08-05 19:00:55 +00:00
"dnd.npc_occurrences" ,
2026-07-23 13:26:27 +00:00
}
var referenceSlotDescriptions = shared . ReferenceSlotDescriptions {
2026-08-05 19:00:55 +00:00
Glossary : "Optional campaign glossary reference material used only for occurrence disambiguation." ,
Party : "Optional party roster reference material used only for occurrence disambiguation." ,
Players : "Optional player list reference material used only for occurrence disambiguation." ,
Roster : "Deprecated alias for party roster reference material used only for occurrence disambiguation." ,
2026-07-23 13:26:27 +00:00
}
func referenceSlots ( ) [ ] contracts . ReferenceSlot {
slots := shared . ReferenceSlots ( referenceSlotDescriptions )
slots = append ( slots , contracts . ReferenceSlot {
Name : NPCRegistryReferenceSlot ,
2026-08-05 19:00:55 +00:00
Description : "Required normalized NPC registry used only for occurrence identity grounding, never as occurrence evidence." ,
2026-07-23 13:26:27 +00:00
Required : true ,
AcceptedMediaTypes : [ ] string { "application/json" } ,
2026-08-05 18:25:04 +00:00
AcceptedArtifactKinds : [ ] contracts . ArtifactKind { dnd . NPCRegistryKind } ,
2026-07-23 13:26:27 +00:00
MaxBytes : NPCRegistryMaxBytes ,
} )
sort . Slice ( slots , func ( i , j int ) bool { return slots [ i ] . Name < slots [ j ] . Name } )
return slots
}
2026-08-05 18:55:58 +00:00
var _ contracts . Extractor [ dnd . NPCOccurrenceList ] = ( * Extractor ) ( nil )
2026-07-23 13:26:27 +00:00
type Options struct { }
type Extractor struct {
2026-11-22 01:03:06 +00:00
engine * promptkit . Engine
npcResolver * npcregistry . Resolver
2026-07-23 13:26:27 +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-07-23 13:26:27 +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 ]
}
npcResolver , err := npcregistry . NewResolver ( referenceSet )
if err != nil {
return nil , extractorErrorf ( "prepare NPC registry prompt input: %w" , err )
}
2026-11-22 01:03:06 +00:00
return & Extractor { engine : engine , npcResolver : npcResolver } , nil
2026-07-23 13:26:27 +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 . NPCOccurrenceList ] ) ( contracts . TypedExtractionResult [ dnd . NPCOccurrenceList ] , error ) {
2026-07-23 13:26:27 +00:00
if e == nil {
2026-08-05 18:55:58 +00:00
return contracts . TypedExtractionResult [ dnd . NPCOccurrenceList ] { } , extractorErrorf ( "extractor must not be nil" )
2026-07-23 13:26:27 +00:00
}
2026-11-22 01:03:06 +00:00
if e . engine == nil {
return contracts . TypedExtractionResult [ dnd . NPCOccurrenceList ] { } , extractorErrorf ( "native engine must not be nil" )
2026-07-23 13:26:27 +00:00
}
2026-07-24 14:38:42 +00:00
sourceInput , err := shared . PrepareChunkExtraction ( ctx , req )
2026-07-23 13:26:27 +00:00
if err != nil {
2026-08-05 18:55:58 +00:00
return contracts . TypedExtractionResult [ dnd . NPCOccurrenceList ] { } , extractorErrorf ( "%w" , err )
2026-07-23 13:26:27 +00:00
}
2026-07-24 14:33:34 +00:00
order := shared . NewSourceRefOrder ( req . Source )
2026-07-23 13:26:27 +00:00
npcRegistry , err := e . npcResolver . Resolve ( req . References )
if err != nil {
2026-08-05 18:55:58 +00:00
return contracts . TypedExtractionResult [ dnd . NPCOccurrenceList ] { } , extractorErrorf ( "resolve NPC registry: %w" , err )
2026-07-23 13:26:27 +00:00
}
if ! npcRegistry . Bound ( ) {
2026-08-05 18:55:58 +00:00
return contracts . TypedExtractionResult [ dnd . NPCOccurrenceList ] { } , extractorErrorf ( "NPC registry reference is required" )
2026-07-23 13:26:27 +00:00
}
2026-11-22 01:03:06 +00:00
sourceID := req . Source . ID
materials := shared . PromptInputs ( sourceInput , req . References )
materials [ NPCRegistryReferenceSlot ] = npcRegistry . 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 . NPCOccurrenceList , [ ] string , error ) {
var response extractionResponse
if err := json . Unmarshal ( [ ] byte ( result . RawOutput ) , & response ) ; err != nil {
return nil , nil , extractorErrorf ( "decode native output: %w" , err )
}
canonicalizeResponse ( & response , order , sourceID )
value , err := canonicalOccurrenceList ( response , sourceID , npcRegistry )
if err != nil {
return nil , [ ] string { "Resolve every occurrence to an exact canonical name from the supplied NPC registry. Omit occurrences for identities absent from that registry; do not invent an identity. 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 . NPCOccurrenceList ) ( dnd . NPCOccurrenceList , error ) {
return dnd . NPCOccurrenceList { Occurrences : [ ] dnd . NPCOccurrence { } } , nil
} )
2026-08-08 14:37:54 +00:00
if err != nil {
2026-11-22 01:03:06 +00:00
return contracts . TypedExtractionResult [ dnd . NPCOccurrenceList ] { } , extractorErrorf ( "produce occurrences: %w" , err )
2026-08-05 18:55:58 +00:00
}
2026-11-22 01:03:06 +00:00
return contracts . TypedExtractionResult [ dnd . NPCOccurrenceList ] { Value : value , Outcome : outcome } , nil
2026-08-05 18:55:58 +00:00
}
2026-07-23 13:26:27 +00:00
func ModuleSpec ( ) pipeline . ModuleSpec {
return pipeline . ModuleSpec {
2026-11-22 01:03:06 +00:00
Key : Key ,
Stage : pipeline . StageExtract ,
ExecutionClass : contracts . ExecutionClassLLMBacked ,
Prompts : [ ] string { PromptID , CorrectionPromptID } ,
Requires : append ( [ ] string ( nil ) , requiredCapabilities ... ) ,
Provides : append ( [ ] string ( nil ) , providedCapabilities ... ) ,
ArtifactKind : dnd . NPCOccurrenceListKind ,
ReferenceSlots : referenceSlots ( ) ,
2026-07-23 13:26:27 +00:00
}
}
func Register ( registry * pipeline . ExtractorRegistry ) error {
2026-08-05 18:55:58 +00:00
return pipeline . RegisterExtractorBuilder ( registry , ModuleSpec ( ) , validateOptions , func ( request pipeline . BuildRequest ) ( contracts . Extractor [ dnd . NPCOccurrenceList ] , error ) {
2026-07-23 13:26:27 +00:00
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-07-23 13:26:27 +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 {
2026-08-05 19:00:55 +00:00
return fmt . Errorf ( "dnd NPC occurrences extractor: " + format , args ... )
2026-07-23 13:26:27 +00:00
}