Ground spell extraction with the effective catalog

internal/modules/dnd/extract/spells/extractor.go

@@ -9,6 +9,7 @@ import (
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+	spellcatalog "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/spells/catalog"
 )
 
 const Key = "dnd/spells"
@@ -31,19 +32,50 @@ var referenceSlotDescriptions = shared.ReferenceSlotDescriptions{
 	Roster:   "Deprecated alias for party roster reference material used only for disambiguation.",
 }
 
+func referenceSlots() []contracts.ReferenceSlot {
+	slots := shared.ReferenceSlots(referenceSlotDescriptions)
+	return append(slots, contracts.ReferenceSlot{
+		Name:               spellcatalog.SpellCatalogReferenceSlot,
+		Description:        "Optional canonical spell-name catalog used for extraction grounding.",
+		AcceptedMediaTypes: []string{"application/json"},
+		MaxBytes:           1048576,
+	})
+}
+
 var _ contracts.Extractor[dnd.SpellList] = (*Extractor)(nil)
 
 type Options struct{}
 
 type Extractor struct {
-	llm contracts.StructuredLLMClient
+	llm                contracts.StructuredLLMClient
+	effectiveCatalog   spellcatalog.EffectiveCatalog
+	catalogPromptInput contracts.LLMInputMaterial
 }
 
-func New(llmClient contracts.StructuredLLMClient, _ Options) (*Extractor, error) {
+func New(llmClient contracts.StructuredLLMClient, _ Options, references ...contracts.ReferenceSet) (*Extractor, error) {
 	if llmClient == nil {
 		return nil, extractorErrorf("LLM client must not be nil")
 	}
-	return &Extractor{llm: llmClient}, 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]
+	}
+	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)
+	}
+	return &Extractor{
+		llm:                llmClient,
+		effectiveCatalog:   effectiveCatalog,
+		catalogPromptInput: catalogPromptInput,
+	}, nil
 }
 
 func (e *Extractor) Key() string {
@@ -51,7 +83,7 @@ func (e *Extractor) Key() string {
 }
 
 func (e *Extractor) ReferenceSlots() []contracts.ReferenceSlot {
-	return shared.ReferenceSlots(referenceSlotDescriptions)
+	return referenceSlots()
 }
 
 func (e *Extractor) ManifestMetadata() map[string]any {
@@ -63,6 +95,9 @@ func (e *Extractor) ManifestMetadata() map[string]any {
 		"prompt_id":            PromptID,
 		"prompt_version":       SchemaVersion,
 		"prompt_sha256":        promptSHA,
+		"catalog_base_id":      e.effectiveCatalog.BaseID(),
+		"catalog_digest":       e.effectiveCatalog.Digest(),
+		"catalog_overlay_ids":  e.effectiveCatalog.OverlayIDs(),
 		"response_schema_key":  string(ResponseSchemaKey),
 		"response_schema_id":   ResponseSchemaID,
 		"response_schema_name": ResponseSchemaName,
@@ -102,13 +137,15 @@ func (e *Extractor) Extract(ctx context.Context, req contracts.TypedExtractionRe
 	}
 
 	var response extractionResponse
+	inputs := shared.PromptInputs(sourceInput, req.References)
+	inputs[spellcatalog.SpellCatalogReferenceSlot] = e.catalogPromptInput.Clone()
 	if _, err := e.llm.CompleteStructured(ctx, contracts.StructuredCompletionRequest{
 		StageName:     Key,
 		PromptID:      PromptID,
 		PromptVersion: SchemaVersion,
 		ProfileID:     req.LLMProfile,
 		SessionID:     req.SessionID,
-		Inputs:        shared.PromptInputs(sourceInput, req.References),
+		Inputs:        inputs,
 	}, &response); err != nil {
 		return contracts.TypedExtractionResult[dnd.SpellList]{}, extractorErrorf("complete structured output: %w", err)
 	}
@@ -143,7 +180,7 @@ func ModuleSpec() pipeline.ModuleSpec {
 		Requires:       append([]string(nil), requiredCapabilities...),
 		Provides:       append([]string(nil), providedCapabilities...),
 		ArtifactKind:   dnd.SpellListKind,
-		ReferenceSlots: shared.ReferenceSlots(referenceSlotDescriptions),
+		ReferenceSlots: referenceSlots(),
 	}
 }
 
@@ -153,7 +190,7 @@ func Register(registry *pipeline.ExtractorRegistry) error {
 		if err != nil {
 			return nil, err
 		}
-		return New(request.Dependencies.LLM, options)
+		return New(request.Dependencies.LLM, options, request.References)
 	})
 }