Files
notarius/internal/modules/dnd/extract/enemyevents/extractor.go

192 lines
7.5 KiB
Go
Raw Normal View History

2026-08-03 20:44:44 +00:00
package enemyevents
import (
"context"
"encoding/json"
2026-08-03 20:44:44 +00:00
"fmt"
"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"
)
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 {
engine *promptkit.Engine
2026-08-03 20:44:44 +00:00
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")
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)
}
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() }
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")
}
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 {
return e.withoutModel(ctx, req, emptyResult())
2026-08-03 20:44:44 +00:00
}
case sceneregistry.MatchMissing, sceneregistry.MatchMismatched:
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)
}
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
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()
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
}
// 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{
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
}
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...)
}