2026-08-03 20:44:44 +00:00
package enemyevents
import (
"context"
2026-11-22 01:20:46 +00:00
"encoding/json"
2026-08-03 20:44:44 +00:00
"fmt"
2026-11-22 01:20:46 +00:00
"strings"
"go.maximumdirect.net/promptkit"
2026-08-03 20:44:44 +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"
sceneregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/scenedescriptions/registry"
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
)
2026-11-22 01:20:46 +00:00
const Key = "dnd/enemy-events"
const PromptID = "notarius/dnd.enemy_events"
const CorrectionPromptID = "notarius/dnd.enemy_events.repair"
2026-08-03 20:44:44 +00:00
var requiredCapabilities = [ ] string {
"chunks" ,
"source.transcript" ,
}
var providedCapabilities = [ ] string {
"dnd.enemy_events" ,
}
var _ contracts . Extractor [ dnd . EnemyEventList ] = ( * Extractor ) ( nil )
type Options struct { }
type Extractor struct {
2026-11-22 01:20:46 +00:00
engine * promptkit . Engine
2026-08-03 20:44:44 +00:00
grounding * groundingResolver
}
2026-11-22 01:20:46 +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-03 20:44:44 +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 ]
}
grounding , err := newGroundingResolver ( referenceSet )
if err != nil {
return nil , extractorErrorf ( "prepare grounding: %w" , err )
}
2026-11-22 01:20:46 +00:00
return & Extractor { engine : engine , grounding : grounding } , nil
2026-08-03 20:44:44 +00:00
}
func ( e * Extractor ) Key ( ) string { return Key }
func ( e * Extractor ) ReferenceSlots ( ) [ ] contracts . ReferenceSlot { return referenceSlots ( ) }
2026-11-22 01:20:46 +00:00
func ( e * Extractor ) Extract ( ctx context . Context , req contracts . TypedExtractionRequest [ dnd . EnemyEventList ] ) ( contracts . TypedExtractionResult [ dnd . EnemyEventList ] , error ) {
2026-08-03 20:44:44 +00:00
if e == nil {
return contracts . TypedExtractionResult [ dnd . EnemyEventList ] { } , extractorErrorf ( "extractor must not be nil" )
}
2026-11-22 01:20:46 +00:00
if e . engine == nil {
return contracts . TypedExtractionResult [ dnd . EnemyEventList ] { } , extractorErrorf ( "native engine must not be nil" )
2026-08-03 20:44:44 +00:00
}
if e . grounding == nil {
return contracts . TypedExtractionResult [ dnd . EnemyEventList ] { } , extractorErrorf ( "grounding resolver must not be nil" )
}
sourceInput , err := shared . PrepareChunkExtraction ( ctx , req )
if err != nil {
return contracts . TypedExtractionResult [ dnd . EnemyEventList ] { } , extractorErrorf ( "%w" , err )
}
match , err := e . grounding . SceneMatch ( req . References , req . Chunk )
if err != nil {
return contracts . TypedExtractionResult [ dnd . EnemyEventList ] { } , extractorErrorf ( "resolve scene eligibility: %w" , err )
}
switch match . State {
case sceneregistry . MatchExact :
if match . Kind != dnd . SceneKindCombat {
2026-11-22 01:20:46 +00:00
return e . withoutModel ( ctx , req , emptyResult ( ) )
2026-08-03 20:44:44 +00:00
}
case sceneregistry . MatchMissing , sceneregistry . MatchMismatched :
2026-11-22 01:20:46 +00:00
return e . withoutModel ( ctx , req , unavailableSceneResult ( ) )
2026-08-03 20:44:44 +00:00
default :
return contracts . TypedExtractionResult [ dnd . EnemyEventList ] { } , extractorErrorf ( "unsupported scene eligibility match state %q" , match . State )
}
grounding , err := e . grounding . Resolve ( req . References )
if err != nil {
return contracts . TypedExtractionResult [ dnd . EnemyEventList ] { } , extractorErrorf ( "resolve enemy-event grounding: %w" , err )
}
2026-11-22 01:20:46 +00:00
order := shared . NewSourceRefOrder ( req . Source )
sourceID := req . Source . ID
materials := shared . PromptInputs ( sourceInput , req . References )
for name , material := range grounding . PromptInputs ( ) {
materials [ name ] = material
}
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 . EnemyEventList , [ ] 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 := canonicalEnemyEventList ( response , order , sourceID )
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 . EnemyEventList ) ( dnd . EnemyEventList , error ) {
return emptyResult ( ) . Value , nil
} )
2026-08-26 23:59:05 +00:00
if err != nil {
2026-11-22 01:20:46 +00:00
return contracts . TypedExtractionResult [ dnd . EnemyEventList ] { } , extractorErrorf ( "produce enemy events: %w" , err )
2026-08-26 23:59:05 +00:00
}
2026-11-22 01:20:46 +00:00
return contracts . TypedExtractionResult [ dnd . EnemyEventList ] { Value : value , Outcome : outcome } , nil
2026-08-03 20:44:44 +00:00
}
func emptyResult ( ) contracts . TypedExtractionResult [ dnd . EnemyEventList ] {
return contracts . TypedExtractionResult [ dnd . EnemyEventList ] { Value : dnd . EnemyEventList { Events : [ ] dnd . EnemyEvent { } } }
}
func unavailableSceneResult ( ) contracts . TypedExtractionResult [ dnd . EnemyEventList ] {
result := emptyResult ( )
2026-08-27 16:04:32 +00:00
result . Diagnostics = [ ] contracts . ProducerDiagnostic { {
Disposition : contracts . DiagnosticDispositionWarning ,
Category : contracts . DiagnosticCategoryDegradation ,
ReasonCode : "scene_classification_unavailable" ,
OccurrenceCount : 1 ,
Samples : [ ] contracts . DiagnosticSample { { Scope : SceneDescriptionReferenceSlot , Message : "No exact scene classification was available; enemy-event extraction was skipped." } } ,
2026-08-03 20:44:44 +00:00
} }
return result
}
2026-11-22 01:20:46 +00:00
// withoutModel assesses a deterministic skip without a native request or cache key.
func ( e * Extractor ) withoutModel ( ctx context . Context , req contracts . TypedExtractionRequest [ dnd . EnemyEventList ] , result contracts . TypedExtractionResult [ dnd . EnemyEventList ] ) ( contracts . TypedExtractionResult [ dnd . EnemyEventList ] , error ) {
value , outcome , err := pipeline . AssessProducer ( ctx , req . Operation , result . Value , func ( context . Context ) ( dnd . EnemyEventList , error ) { return emptyResult ( ) . Value , nil } )
if err != nil {
return contracts . TypedExtractionResult [ dnd . EnemyEventList ] { } , extractorErrorf ( "assess skipped enemy extraction: %w" , err )
}
result . Value , result . Outcome = value , outcome
return result , nil
}
2026-08-03 20:44:44 +00:00
func ModuleSpec ( ) pipeline . ModuleSpec {
return pipeline . ModuleSpec {
2026-11-22 01:20:46 +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 . EnemyEventListKind ,
ReferenceSlots : referenceSlots ( ) ,
2026-08-03 20:44:44 +00:00
}
}
func Register ( registry * pipeline . ExtractorRegistry ) error {
return pipeline . RegisterExtractorBuilder ( registry , ModuleSpec ( ) , validateOptions , func ( request pipeline . BuildRequest ) ( contracts . Extractor [ dnd . EnemyEventList ] , error ) {
options , err := DecodeOptions ( request . Options )
if err != nil {
return nil , err
}
2026-11-22 01:20:46 +00:00
return New ( request . Dependencies . Engine , options , request . References )
2026-08-03 20:44:44 +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 enemy events extractor: " + format , args ... )
}