2026-07-21 05:08:02 +00:00
package combatturns
import (
"context"
2026-11-22 01:13:57 +00:00
"encoding/json"
2026-07-21 05:08:02 +00:00
"fmt"
"sort"
2026-11-22 01:13:57 +00:00
"strings"
"go.maximumdirect.net/promptkit"
2026-07-21 05:08:02 +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"
2026-07-25 19:23:19 +00:00
sceneregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/scenedescriptions/registry"
2026-07-21 05:08:02 +00:00
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
)
2026-11-22 01:13:57 +00:00
const Key = "dnd/combat-turns"
const PromptID = "notarius/dnd.combat_turns"
const CorrectionPromptID = "notarius/dnd.combat_turns.repair"
2026-07-21 05:08:02 +00:00
const (
2026-07-25 19:23:19 +00:00
NPCRegistryReferenceSlot = npcregistry . ReferenceSlot
NPCRegistryMaxBytes = npcregistry . MaxBytes
SceneDescriptionReferenceSlot = sceneregistry . ReferenceSlot
SceneDescriptionMaxBytes = sceneregistry . MaxBytes
2026-07-21 05:08:02 +00:00
)
var requiredCapabilities = [ ] string {
"chunks" ,
"source.transcript" ,
}
var providedCapabilities = [ ] string {
"dnd.combat_turns" ,
}
var referenceSlotDescriptions = shared . ReferenceSlotDescriptions {
Glossary : "Optional campaign glossary reference material used only for disambiguation." ,
Party : "Optional party roster reference material used only for disambiguation." ,
Players : "Optional player list reference material used only for disambiguation." ,
Roster : "Deprecated alias for party roster reference material used only for disambiguation." ,
}
func referenceSlots ( ) [ ] contracts . ReferenceSlot {
slots := shared . ReferenceSlots ( referenceSlotDescriptions )
slots = append ( slots , contracts . ReferenceSlot {
2026-07-21 21:05:28 +00:00
Name : NPCRegistryReferenceSlot ,
2026-07-22 19:14:14 +00:00
Description : "Optional normalized NPC registry used for canonical actor grounding." ,
2026-07-21 21:05:28 +00:00
AcceptedMediaTypes : [ ] string { "application/json" } ,
2026-08-05 18:25:04 +00:00
AcceptedArtifactKinds : [ ] contracts . ArtifactKind { dnd . NPCRegistryKind } ,
2026-07-21 21:05:28 +00:00
MaxBytes : NPCRegistryMaxBytes ,
2026-07-21 05:08:02 +00:00
} )
2026-07-25 19:23:19 +00:00
slots = append ( slots , contracts . ReferenceSlot {
Name : SceneDescriptionReferenceSlot ,
Description : "Required scene descriptions that gate combat eligibility and are not combat evidence." ,
Required : true ,
AcceptedMediaTypes : [ ] string { "application/json" } ,
AcceptedArtifactKinds : [ ] contracts . ArtifactKind { dnd . SceneDescriptionListKind } ,
MaxBytes : SceneDescriptionMaxBytes ,
} )
2026-07-21 05:08:02 +00:00
sort . Slice ( slots , func ( i , j int ) bool { return slots [ i ] . Name < slots [ j ] . Name } )
return slots
}
var _ contracts . Extractor [ dnd . CombatTurnList ] = ( * Extractor ) ( nil )
type Options struct { }
type Extractor struct {
2026-11-22 01:13:57 +00:00
engine * promptkit . Engine
npcResolver * npcregistry . Resolver
sceneResolver * sceneregistry . Resolver
2026-07-21 05:08:02 +00:00
}
2026-11-22 01:13:57 +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-21 05:08:02 +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 ]
}
2026-07-21 22:12:01 +00:00
npcResolver , err := npcregistry . NewResolver ( referenceSet )
2026-07-21 05:08:02 +00:00
if err != nil {
return nil , extractorErrorf ( "prepare NPC registry prompt input: %w" , err )
}
2026-07-25 19:23:19 +00:00
sceneResolver , err := sceneregistry . NewResolver ( referenceSet )
if err != nil {
return nil , extractorErrorf ( "prepare scene eligibility: %w" , err )
}
2026-11-22 01:13:57 +00:00
return & Extractor { engine : engine , npcResolver : npcResolver , sceneResolver : sceneResolver } , nil
2026-07-21 05:08:02 +00:00
}
func ( e * Extractor ) Key ( ) string { return Key }
func ( e * Extractor ) ReferenceSlots ( ) [ ] contracts . ReferenceSlot { return referenceSlots ( ) }
2026-11-22 01:13:57 +00:00
func ( e * Extractor ) Extract ( ctx context . Context , req contracts . TypedExtractionRequest [ dnd . CombatTurnList ] ) ( contracts . TypedExtractionResult [ dnd . CombatTurnList ] , error ) {
2026-07-21 05:08:02 +00:00
if e == nil {
return contracts . TypedExtractionResult [ dnd . CombatTurnList ] { } , extractorErrorf ( "extractor must not be nil" )
}
2026-11-22 01:13:57 +00:00
if e . engine == nil {
return contracts . TypedExtractionResult [ dnd . CombatTurnList ] { } , extractorErrorf ( "native engine must not be nil" )
2026-07-21 05:08:02 +00:00
}
2026-07-24 14:38:42 +00:00
sourceInput , err := shared . PrepareChunkExtraction ( ctx , req )
2026-07-21 05:08:02 +00:00
if err != nil {
2026-07-21 14:27:39 +00:00
return contracts . TypedExtractionResult [ dnd . CombatTurnList ] { } , extractorErrorf ( "%w" , err )
2026-07-21 05:08:02 +00:00
}
2026-07-25 19:23:19 +00:00
if _ , ok := req . References . Slots [ SceneDescriptionReferenceSlot ] ; ! ok {
return contracts . TypedExtractionResult [ dnd . CombatTurnList ] { } , extractorErrorf ( "required scene descriptions reference is missing" )
}
scenes , err := e . sceneResolver . Resolve ( req . References )
if err != nil {
return contracts . TypedExtractionResult [ dnd . CombatTurnList ] { } , extractorErrorf ( "resolve scene eligibility: %w" , err )
}
match := scenes . Match ( req . Chunk )
switch match . State {
case sceneregistry . MatchExact :
if match . Kind != dnd . SceneKindCombat {
2026-11-22 01:13:57 +00:00
return e . withoutModel ( ctx , req , nil )
2026-07-25 19:23:19 +00:00
}
case sceneregistry . MatchMissing , sceneregistry . MatchMismatched :
2026-11-22 01:13:57 +00:00
return e . withoutModel ( ctx , req , [ ] 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; combat extraction was skipped." } } ,
} } )
2026-07-25 21:08:24 +00:00
default :
return contracts . TypedExtractionResult [ dnd . CombatTurnList ] { } , extractorErrorf ( "unsupported scene eligibility match state %q" , match . State )
2026-07-25 19:23:19 +00:00
}
2026-07-24 14:33:34 +00:00
order := shared . NewSourceRefOrder ( req . Source )
2026-07-21 22:12:01 +00:00
npcRegistry , err := e . npcResolver . Resolve ( req . References )
if err != nil {
return contracts . TypedExtractionResult [ dnd . CombatTurnList ] { } , extractorErrorf ( "resolve NPC registry: %w" , err )
}
2026-07-21 05:08:02 +00:00
2026-11-22 01:13:57 +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 . CombatTurnList , [ ] 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 := canonicalCombatTurnList ( response , 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 . CombatTurnList ) ( dnd . CombatTurnList , error ) {
return dnd . CombatTurnList { CombatTurns : [ ] dnd . CombatTurn { } } , nil
} )
2026-08-26 23:59:05 +00:00
if err != nil {
2026-11-22 01:13:57 +00:00
return contracts . TypedExtractionResult [ dnd . CombatTurnList ] { } , extractorErrorf ( "produce combat turns: %w" , err )
2026-07-21 05:08:02 +00:00
}
2026-11-22 01:13:57 +00:00
return contracts . TypedExtractionResult [ dnd . CombatTurnList ] { Value : value , Outcome : outcome } , nil
}
// withoutModel assesses the deterministic empty result without native preparation.
func ( e * Extractor ) withoutModel ( ctx context . Context , req contracts . TypedExtractionRequest [ dnd . CombatTurnList ] , diagnostics [ ] contracts . ProducerDiagnostic ) ( contracts . TypedExtractionResult [ dnd . CombatTurnList ] , error ) {
empty := dnd . CombatTurnList { CombatTurns : [ ] dnd . CombatTurn { } }
value , outcome , err := pipeline . AssessProducer ( ctx , req . Operation , empty , func ( context . Context ) ( dnd . CombatTurnList , error ) {
return dnd . CombatTurnList { CombatTurns : [ ] dnd . CombatTurn { } } , nil
} )
2026-08-26 23:59:05 +00:00
if err != nil {
2026-11-22 01:13:57 +00:00
return contracts . TypedExtractionResult [ dnd . CombatTurnList ] { } , extractorErrorf ( "assess skipped combat extraction: %w" , err )
2026-08-26 23:59:05 +00:00
}
2026-11-22 01:13:57 +00:00
return contracts . TypedExtractionResult [ dnd . CombatTurnList ] { Value : value , Outcome : outcome , Diagnostics : diagnostics } , nil
2026-07-21 05:08:02 +00:00
}
func ModuleSpec ( ) pipeline . ModuleSpec {
return pipeline . ModuleSpec {
2026-11-22 01:13:57 +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 . CombatTurnListKind ,
ReferenceSlots : referenceSlots ( ) ,
2026-07-21 05:08:02 +00:00
}
}
func Register ( registry * pipeline . ExtractorRegistry ) error {
return pipeline . RegisterExtractorBuilder ( registry , ModuleSpec ( ) , validateOptions , func ( request pipeline . BuildRequest ) ( contracts . Extractor [ dnd . CombatTurnList ] , error ) {
options , err := DecodeOptions ( request . Options )
if err != nil {
return nil , err
}
2026-11-22 01:13:57 +00:00
return New ( request . Dependencies . Engine , options , request . References )
2026-07-21 05:08:02 +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 combat turns extractor: " + format , args ... )
}