2026-08-05 20:00:20 +00:00
// Package itemoccurrences extracts source-grounded D&D item occurrences.
package itemoccurrences
2026-07-25 21:49:24 +00:00
import (
"context"
2026-11-22 01:08:02 +00:00
"encoding/json"
2026-07-25 21:49:24 +00:00
"fmt"
2026-08-05 19:55:34 +00:00
"sort"
2026-11-22 01:08:02 +00:00
"strings"
"go.maximumdirect.net/promptkit"
2026-07-25 21:49:24 +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"
2026-08-05 19:55:34 +00:00
itemregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/items/registry"
2026-07-25 21:49:24 +00:00
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
)
2026-08-05 20:00:20 +00:00
const Key = "dnd/item-occurrences"
2026-11-22 01:08:02 +00:00
const PromptID = "notarius/dnd.item_occurrences"
const CorrectionPromptID = "notarius/dnd.item_occurrences.repair"
2026-07-25 21:49:24 +00:00
2026-08-05 19:55:34 +00:00
const (
ItemRegistryReferenceSlot = itemregistry . ReferenceSlot
ItemRegistryMaxBytes = itemregistry . MaxBytes
)
2026-07-25 21:49:24 +00:00
var requiredCapabilities = [ ] string {
"chunks" ,
"source.transcript" ,
}
var providedCapabilities = [ ] string {
2026-08-05 20:00:20 +00:00
"dnd.item_occurrences" ,
2026-07-25 21:49:24 +00:00
}
var referenceSlotDescriptions = shared . ReferenceSlotDescriptions {
Glossary : "Optional campaign glossary reference material used only for item and holder disambiguation." ,
Party : "Optional party roster reference material used only for item and holder disambiguation." ,
Players : "Optional player list reference material used only for item and holder disambiguation." ,
Roster : "Deprecated alias for party roster reference material used only for item and holder disambiguation." ,
}
func referenceSlots ( ) [ ] contracts . ReferenceSlot {
2026-08-05 19:55:34 +00:00
slots := shared . ReferenceSlots ( referenceSlotDescriptions )
slots = append ( slots , contracts . ReferenceSlot {
Name : ItemRegistryReferenceSlot ,
Description : "Required normalized item registry used only for item identity grounding, never as occurrence evidence." ,
Required : true ,
AcceptedMediaTypes : [ ] string { "application/json" } ,
AcceptedArtifactKinds : [ ] contracts . ArtifactKind { dnd . ItemRegistryKind } ,
MaxBytes : ItemRegistryMaxBytes ,
} )
sort . Slice ( slots , func ( left , right int ) bool { return slots [ left ] . Name < slots [ right ] . Name } )
return slots
2026-07-25 21:49:24 +00:00
}
2026-08-05 19:55:34 +00:00
var _ contracts . Extractor [ dnd . ItemOccurrenceList ] = ( * Extractor ) ( nil )
2026-07-25 21:49:24 +00:00
type Options struct { }
type Extractor struct {
2026-11-22 01:08:02 +00:00
engine * promptkit . Engine
itemResolver * itemregistry . Resolver
2026-07-25 21:49:24 +00:00
}
2026-11-22 01:08:02 +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-25 21:49:24 +00:00
}
if len ( references ) > 1 {
return nil , extractorErrorf ( "at most one reference set may be supplied" )
}
2026-08-05 19:55:34 +00:00
var referenceSet contracts . ReferenceSet
if len ( references ) == 1 {
referenceSet = references [ 0 ]
}
itemResolver , err := itemregistry . NewResolver ( referenceSet )
if err != nil {
return nil , extractorErrorf ( "prepare item registry prompt input: %w" , err )
}
2026-11-22 01:08:02 +00:00
return & Extractor { engine : engine , itemResolver : itemResolver } , nil
2026-07-25 21:49:24 +00:00
}
func ( e * Extractor ) Key ( ) string { return Key }
func ( e * Extractor ) ReferenceSlots ( ) [ ] contracts . ReferenceSlot { return referenceSlots ( ) }
2026-11-22 01:08:02 +00:00
func ( e * Extractor ) Extract ( ctx context . Context , req contracts . TypedExtractionRequest [ dnd . ItemOccurrenceList ] ) ( contracts . TypedExtractionResult [ dnd . ItemOccurrenceList ] , error ) {
2026-07-25 21:49:24 +00:00
if e == nil {
2026-08-05 19:55:34 +00:00
return contracts . TypedExtractionResult [ dnd . ItemOccurrenceList ] { } , extractorErrorf ( "extractor must not be nil" )
2026-07-25 21:49:24 +00:00
}
2026-11-22 01:08:02 +00:00
if e . engine == nil {
return contracts . TypedExtractionResult [ dnd . ItemOccurrenceList ] { } , extractorErrorf ( "native engine must not be nil" )
2026-07-25 21:49:24 +00:00
}
sourceInput , err := shared . PrepareChunkExtraction ( ctx , req )
if err != nil {
2026-08-05 19:55:34 +00:00
return contracts . TypedExtractionResult [ dnd . ItemOccurrenceList ] { } , extractorErrorf ( "%w" , err )
2026-07-25 21:49:24 +00:00
}
order := shared . NewSourceRefOrder ( req . Source )
2026-08-05 19:55:34 +00:00
registry , err := e . itemResolver . Resolve ( req . References )
if err != nil {
return contracts . TypedExtractionResult [ dnd . ItemOccurrenceList ] { } , extractorErrorf ( "resolve item registry: %w" , err )
}
if ! registry . Bound ( ) {
return contracts . TypedExtractionResult [ dnd . ItemOccurrenceList ] { } , extractorErrorf ( "item registry reference is required" )
}
2026-11-22 01:08:02 +00:00
sourceID := req . Source . ID
materials := shared . PromptInputs ( sourceInput , req . References )
materials [ ItemRegistryReferenceSlot ] = registry . 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 . ItemOccurrenceList , [ ] 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 := canonicalItemOccurrenceList ( response , order , sourceID , registry )
if err != nil {
return nil , [ ] string { "Select the exact canonical item name from the supplied registry for every occurrence. Omit unsupported or ambiguous selections; do not invent an item. Return the complete replacement occurrence list, keeping current-transcript evidence separate from registry context." } , 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 . ItemOccurrenceList ) ( dnd . ItemOccurrenceList , error ) {
return dnd . ItemOccurrenceList { Occurrences : [ ] dnd . ItemOccurrence { } } , nil
} )
2026-08-08 14:43:04 +00:00
if err != nil {
2026-11-22 01:08:02 +00:00
return contracts . TypedExtractionResult [ dnd . ItemOccurrenceList ] { } , extractorErrorf ( "produce occurrences: %w" , err )
2026-08-08 14:43:04 +00:00
}
2026-11-22 01:08:02 +00:00
return contracts . TypedExtractionResult [ dnd . ItemOccurrenceList ] { Value : value , Outcome : outcome } , nil
2026-07-25 21:49:24 +00:00
}
func ModuleSpec ( ) pipeline . ModuleSpec {
return pipeline . ModuleSpec {
2026-11-22 01:08:02 +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 . ItemOccurrenceListKind ,
ReferenceSlots : referenceSlots ( ) ,
2026-07-25 21:49:24 +00:00
}
}
func Register ( registry * pipeline . ExtractorRegistry ) error {
2026-08-05 19:55:34 +00:00
return pipeline . RegisterExtractorBuilder ( registry , ModuleSpec ( ) , validateOptions , func ( request pipeline . BuildRequest ) ( contracts . Extractor [ dnd . ItemOccurrenceList ] , error ) {
2026-07-25 21:49:24 +00:00
options , err := DecodeOptions ( request . Options )
if err != nil {
return nil , err
}
2026-11-22 01:08:02 +00:00
return New ( request . Dependencies . Engine , options , request . References )
2026-07-25 21:49:24 +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:55:34 +00:00
return fmt . Errorf ( "dnd item occurrences extractor: " + format , args ... )
2026-07-25 21:49:24 +00:00
}