package enemyevents import ( "context" "encoding/json" "fmt" "strings" "go.maximumdirect.net/promptkit" "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" ) const Key = "dnd/enemy-events" const PromptID = "notarius/dnd.enemy_events" const CorrectionPromptID = "notarius/dnd.enemy_events.repair" 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 { engine *promptkit.Engine grounding *groundingResolver } func New(engine *promptkit.Engine, _ Options, references ...contracts.ReferenceSet) (*Extractor, error) { if engine == nil { return nil, extractorErrorf("native engine must not be nil") } 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) } return &Extractor{engine: engine, grounding: grounding}, nil } func (e *Extractor) Key() string { return Key } func (e *Extractor) ReferenceSlots() []contracts.ReferenceSlot { return referenceSlots() } func (e *Extractor) Extract(ctx context.Context, req contracts.TypedExtractionRequest[dnd.EnemyEventList]) (contracts.TypedExtractionResult[dnd.EnemyEventList], error) { if e == nil { return contracts.TypedExtractionResult[dnd.EnemyEventList]{}, extractorErrorf("extractor must not be nil") } if e.engine == nil { return contracts.TypedExtractionResult[dnd.EnemyEventList]{}, extractorErrorf("native engine must not be nil") } 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 { return e.withoutModel(ctx, req, emptyResult()) } case sceneregistry.MatchMissing, sceneregistry.MatchMismatched: return e.withoutModel(ctx, req, unavailableSceneResult()) 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) } 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 }) if err != nil { return contracts.TypedExtractionResult[dnd.EnemyEventList]{}, extractorErrorf("produce enemy events: %w", err) } return contracts.TypedExtractionResult[dnd.EnemyEventList]{Value: value, Outcome: outcome}, nil } 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() 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."}}, }} return result } // 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 } func ModuleSpec() pipeline.ModuleSpec { return pipeline.ModuleSpec{ 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(), } } 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 } return New(request.Dependencies.Engine, options, request.References) }) } 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...) }