2026-07-03 23:29:08 +00:00
|
|
|
package spells
|
|
|
|
|
|
|
|
|
|
import (
|
|
|
|
|
"context"
|
2026-11-22 00:02:13 +00:00
|
|
|
"encoding/json"
|
2026-07-03 23:29:08 +00:00
|
|
|
"fmt"
|
2026-07-21 03:12:03 +00:00
|
|
|
"sort"
|
2026-11-22 00:02:13 +00:00
|
|
|
"strings"
|
|
|
|
|
|
|
|
|
|
"go.maximumdirect.net/promptkit"
|
2026-07-03 23:29:08 +00:00
|
|
|
|
|
|
|
|
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
|
|
|
|
|
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
|
2026-07-17 06:50:08 +00:00
|
|
|
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
|
2026-07-21 04:34:56 +00:00
|
|
|
npcregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/registry"
|
2026-07-17 05:05:48 +00:00
|
|
|
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
|
2026-07-20 19:20:56 +00:00
|
|
|
spellcatalog "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/spells/catalog"
|
2026-07-03 23:29:08 +00:00
|
|
|
)
|
|
|
|
|
|
|
|
|
|
const Key = "dnd/spells"
|
2026-11-22 00:02:13 +00:00
|
|
|
const PromptID = "notarius/dnd.spells"
|
|
|
|
|
const CorrectionPromptID = "notarius/dnd.spells.repair"
|
2026-07-24 14:23:35 +00:00
|
|
|
|
2026-07-21 04:34:56 +00:00
|
|
|
const (
|
|
|
|
|
NPCRegistryReferenceSlot = npcregistry.ReferenceSlot
|
|
|
|
|
NPCRegistryMaxBytes = npcregistry.MaxBytes
|
|
|
|
|
)
|
|
|
|
|
|
2026-07-03 23:29:08 +00:00
|
|
|
var requiredCapabilities = []string{
|
|
|
|
|
"chunks",
|
|
|
|
|
"source.transcript",
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
var providedCapabilities = []string{
|
|
|
|
|
"dnd.spell_casts",
|
|
|
|
|
}
|
|
|
|
|
|
2026-07-17 05:05:48 +00:00
|
|
|
var referenceSlotDescriptions = shared.ReferenceSlotDescriptions{
|
2026-07-06 17:22:21 +00:00
|
|
|
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.",
|
2026-07-05 14:49:17 +00:00
|
|
|
}
|
|
|
|
|
|
2026-07-20 19:20:56 +00:00
|
|
|
func referenceSlots() []contracts.ReferenceSlot {
|
|
|
|
|
slots := shared.ReferenceSlots(referenceSlotDescriptions)
|
2026-07-21 03:12:03 +00:00
|
|
|
slots = append(slots, contracts.ReferenceSlot{
|
2026-07-20 19:20:56 +00:00
|
|
|
Name: spellcatalog.SpellCatalogReferenceSlot,
|
|
|
|
|
Description: "Optional canonical spell-name catalog used for extraction grounding.",
|
|
|
|
|
AcceptedMediaTypes: []string{"application/json"},
|
|
|
|
|
MaxBytes: 1048576,
|
2026-07-21 03:12:03 +00:00
|
|
|
}, contracts.ReferenceSlot{
|
2026-07-21 21:05:28 +00:00
|
|
|
Name: NPCRegistryReferenceSlot,
|
|
|
|
|
Description: "Optional normalized NPC registry used for canonical caster-name grounding.",
|
|
|
|
|
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-20 19:20:56 +00:00
|
|
|
})
|
2026-07-21 03:12:03 +00:00
|
|
|
sort.Slice(slots, func(i, j int) bool { return slots[i].Name < slots[j].Name })
|
|
|
|
|
return slots
|
2026-07-20 19:20:56 +00:00
|
|
|
}
|
|
|
|
|
|
2026-07-17 06:50:08 +00:00
|
|
|
var _ contracts.Extractor[dnd.SpellList] = (*Extractor)(nil)
|
2026-07-03 23:29:08 +00:00
|
|
|
|
2026-07-17 06:50:08 +00:00
|
|
|
type Options struct{}
|
2026-07-03 23:29:08 +00:00
|
|
|
|
2026-07-17 06:50:08 +00:00
|
|
|
type Extractor struct {
|
2026-11-22 00:02:13 +00:00
|
|
|
engine *promptkit.Engine
|
|
|
|
|
catalogPromptInput []byte
|
2026-07-21 22:12:01 +00:00
|
|
|
npcResolver *npcregistry.Resolver
|
2026-07-17 06:50:08 +00:00
|
|
|
}
|
|
|
|
|
|
2026-11-22 00:02:13 +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-17 06:50:08 +00:00
|
|
|
}
|
2026-07-20 19:20:56 +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]
|
|
|
|
|
}
|
|
|
|
|
effectiveCatalog, err := spellcatalog.ResolveEffectiveCatalog(referenceSet)
|
|
|
|
|
if err != nil {
|
|
|
|
|
return nil, extractorErrorf("resolve effective spell catalog: %w", err)
|
|
|
|
|
}
|
|
|
|
|
catalogPromptInput, err := newCatalogPromptInput(effectiveCatalog)
|
|
|
|
|
if err != nil {
|
|
|
|
|
return nil, extractorErrorf("prepare spell catalog prompt input: %w", err)
|
|
|
|
|
}
|
2026-07-21 22:12:01 +00:00
|
|
|
npcResolver, err := npcregistry.NewResolver(referenceSet)
|
2026-07-21 03:12:03 +00:00
|
|
|
if err != nil {
|
|
|
|
|
return nil, extractorErrorf("prepare NPC registry prompt input: %w", err)
|
|
|
|
|
}
|
2026-11-22 00:02:13 +00:00
|
|
|
return &Extractor{engine: engine, catalogPromptInput: catalogPromptInput, npcResolver: npcResolver}, nil
|
2026-07-03 23:29:08 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func (e *Extractor) Key() string {
|
|
|
|
|
return Key
|
|
|
|
|
}
|
|
|
|
|
|
2026-07-05 14:13:48 +00:00
|
|
|
func (e *Extractor) ReferenceSlots() []contracts.ReferenceSlot {
|
2026-07-20 19:20:56 +00:00
|
|
|
return referenceSlots()
|
2026-07-05 14:13:48 +00:00
|
|
|
}
|
|
|
|
|
|
2026-11-22 00:02:13 +00:00
|
|
|
func (e *Extractor) Extract(ctx context.Context, req contracts.TypedExtractionRequest[dnd.SpellList]) (contracts.TypedExtractionResult[dnd.SpellList], error) {
|
2026-07-03 23:38:41 +00:00
|
|
|
if e == nil {
|
2026-07-17 06:50:08 +00:00
|
|
|
return contracts.TypedExtractionResult[dnd.SpellList]{}, extractorErrorf("extractor must not be nil")
|
|
|
|
|
}
|
2026-11-22 00:02:13 +00:00
|
|
|
if e.engine == nil {
|
|
|
|
|
return contracts.TypedExtractionResult[dnd.SpellList]{}, extractorErrorf("native engine must not be nil")
|
2026-07-03 23:38:41 +00:00
|
|
|
}
|
2026-07-24 14:38:42 +00:00
|
|
|
sourceInput, err := shared.PrepareChunkExtraction(ctx, req)
|
2026-07-07 15:32:35 -05:00
|
|
|
if err != nil {
|
2026-07-21 14:27:39 +00:00
|
|
|
return contracts.TypedExtractionResult[dnd.SpellList]{}, extractorErrorf("%w", err)
|
2026-07-07 15:32:35 -05:00
|
|
|
}
|
2026-11-22 00:02:13 +00:00
|
|
|
sourceID := req.Source.ID
|
2026-07-24 14:29:19 +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.SpellList]{}, extractorErrorf("resolve NPC registry: %w", err)
|
|
|
|
|
}
|
2026-07-03 23:38:41 +00:00
|
|
|
|
2026-11-22 00:02:13 +00:00
|
|
|
materials := shared.PromptInputs(sourceInput, req.References)
|
|
|
|
|
inputs := make(map[string]promptkit.ArtifactRef, len(materials)+2)
|
|
|
|
|
for name, material := range materials {
|
|
|
|
|
inputs[name] = promptkit.InlineWithURI(material.OriginURI, string(material.Content))
|
|
|
|
|
}
|
|
|
|
|
inputs[spellcatalog.SpellCatalogReferenceSlot] = promptkit.Inline(string(e.catalogPromptInput))
|
|
|
|
|
registryInput := npcRegistry.PromptInput()
|
|
|
|
|
inputs[NPCRegistryReferenceSlot] = promptkit.Inline(string(registryInput.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.SpellList, []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 := canonicalSpellList(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.SpellList) (dnd.SpellList, error) {
|
|
|
|
|
return dnd.SpellList{SpellCasts: []dnd.SpellCast{}}, nil
|
|
|
|
|
})
|
2026-08-26 23:55:23 +00:00
|
|
|
if err != nil {
|
2026-11-22 00:02:13 +00:00
|
|
|
return contracts.TypedExtractionResult[dnd.SpellList]{}, extractorErrorf("produce spells: %w", err)
|
2026-08-26 23:55:23 +00:00
|
|
|
}
|
2026-11-22 00:02:13 +00:00
|
|
|
return contracts.TypedExtractionResult[dnd.SpellList]{Value: value, Outcome: outcome}, nil
|
2026-07-03 23:29:08 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func ModuleSpec() pipeline.ModuleSpec {
|
|
|
|
|
return pipeline.ModuleSpec{
|
2026-11-22 00:02:13 +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.SpellListKind,
|
|
|
|
|
ReferenceSlots: referenceSlots(),
|
2026-07-03 23:29:08 +00:00
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func Register(registry *pipeline.ExtractorRegistry) error {
|
2026-07-17 06:50:08 +00:00
|
|
|
return pipeline.RegisterExtractorBuilder(registry, ModuleSpec(), validateOptions, func(request pipeline.BuildRequest) (contracts.Extractor[dnd.SpellList], error) {
|
|
|
|
|
options, err := DecodeOptions(request.Options)
|
|
|
|
|
if err != nil {
|
|
|
|
|
return nil, err
|
|
|
|
|
}
|
2026-11-22 00:02:13 +00:00
|
|
|
return New(request.Dependencies.Engine, options, request.References)
|
2026-07-03 23:29:08 +00:00
|
|
|
})
|
|
|
|
|
}
|
2026-07-03 23:38:41 +00:00
|
|
|
|
2026-07-17 06:50:08 +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
|
|
|
|
|
}
|
|
|
|
|
|
2026-07-03 23:38:41 +00:00
|
|
|
func extractorErrorf(format string, args ...any) error {
|
|
|
|
|
return fmt.Errorf("dnd spells extractor: "+format, args...)
|
|
|
|
|
}
|