diff --git a/internal/modules/dnd/extract/locations/assets.go b/internal/modules/dnd/extract/locations/assets.go new file mode 100644 index 0000000..306b349 --- /dev/null +++ b/internal/modules/dnd/extract/locations/assets.go @@ -0,0 +1,6 @@ +package locations + +import "embed" + +//go:embed assets/prompts/*.yaml assets/prompts/*.md assets/schemas/*.json +var embeddedAssets embed.FS diff --git a/internal/modules/dnd/extract/locations/assets/prompts/dnd.locations.yaml b/internal/modules/dnd/extract/locations/assets/prompts/dnd.locations.yaml new file mode 100644 index 0000000..27fcd4f --- /dev/null +++ b/internal/modules/dnd/extract/locations/assets/prompts/dnd.locations.yaml @@ -0,0 +1,42 @@ +id: dnd.locations +version: "v1" +default_profile: dnd-extraction +inputs: + - name: transcript + required: true + content_type: application/json + - name: players + required: false + content_type: text/plain + - name: party + required: false + content_type: text/plain + - name: glossary + required: false + content_type: text/plain +messages: + - role: system + content_file: ./sharedassets/common-dnd-system.md + - role: user + content_file: ./sharedassets/common-dnd-identity.md + - role: user + content_file: ./sharedassets/common-dnd-references.md + cache_control: + type: ephemeral + - role: user + content_file: ./sharedassets/common-dnd-transcript.md + cache_control: + type: ephemeral + - role: user + content_file: ./sharedassets/common-dnd-extraction-evidence.md + - role: user + content_file: ./task.md + - role: user + content_file: ./instructions.md + cache_control: + type: ephemeral +output: + format: json + validation_mode: json_schema + schema_path: dnd_locations_llm.v1.json + repair_attempts: 0 diff --git a/internal/modules/dnd/extract/locations/assets/prompts/instructions.md b/internal/modules/dnd/extract/locations/assets/prompts/instructions.md new file mode 100644 index 0000000..aefa071 --- /dev/null +++ b/internal/modules/dnd/extract/locations/assets/prompts/instructions.md @@ -0,0 +1,6 @@ +Return only observed location display names and narrow transcript source ranges. + +Exclude people, creatures, objects, organizations, abstract concepts, and +places merely inferred from an event. Omit uncertain or unsupported places. +Campaign references may clarify terms already present in the transcript, but +they are not evidence and must never supply a source range. diff --git a/internal/modules/dnd/extract/locations/assets/prompts/task.md b/internal/modules/dnd/extract/locations/assets/prompts/task.md new file mode 100644 index 0000000..5b82c2f --- /dev/null +++ b/internal/modules/dnd/extract/locations/assets/prompts/task.md @@ -0,0 +1,8 @@ +Extract physical places established by the provided Dungeons & Dragons +transcript and cite where each place is identified. + +Include planes, regions, settlements, districts, buildings, rooms, landmarks, +routes, and geographic features. A generic label such as "the tavern" is +allowed only when the transcript uses it for a specific place. Keep aliases and +nested places when the transcript identifies them; do not merge or invent +qualifiers for similarly named places. diff --git a/internal/modules/dnd/extract/locations/assets/schemas/dnd_locations_llm.v1.json b/internal/modules/dnd/extract/locations/assets/schemas/dnd_locations_llm.v1.json new file mode 100644 index 0000000..7cf5f86 --- /dev/null +++ b/internal/modules/dnd/extract/locations/assets/schemas/dnd_locations_llm.v1.json @@ -0,0 +1,32 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "notarius.dnd.locations.llm", + "type": "object", + "additionalProperties": false, + "required": ["locations"], + "properties": { + "locations": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["name", "source_refs"], + "properties": { + "name": {"type": "string"}, + "source_refs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["start_unit_id", "end_unit_id"], + "properties": { + "start_unit_id": {"type": "integer"}, + "end_unit_id": {"type": "integer"} + } + } + } + } + } + } + } +} diff --git a/internal/modules/dnd/extract/locations/canonicalize.go b/internal/modules/dnd/extract/locations/canonicalize.go new file mode 100644 index 0000000..301bc02 --- /dev/null +++ b/internal/modules/dnd/extract/locations/canonicalize.go @@ -0,0 +1,86 @@ +package locations + +import ( + "sort" + + "gitea.maximumdirect.net/eric/notarius/internal/core/source" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/locations/identity" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared" +) + +type orderedLocationResponse struct { + value locationResponse + earliest int + hasEvidence bool +} + +func canonicalizeResponse(response *extractionResponse, order shared.SourceRefOrder, sourceID string) { + if response == nil { + return + } + ordered := make([]orderedLocationResponse, len(response.Locations)) + for index := range response.Locations { + earliest, hasEvidence := canonicalizeLocation(&response.Locations[index], order, sourceID) + ordered[index] = orderedLocationResponse{value: response.Locations[index], earliest: earliest, hasEvidence: hasEvidence} + } + sort.SliceStable(ordered, func(left, right int) bool { + if ordered[left].hasEvidence != ordered[right].hasEvidence { + return ordered[left].hasEvidence + } + if !ordered[left].hasEvidence { + return false + } + return ordered[left].earliest < ordered[right].earliest + }) + for index := range ordered { + response.Locations[index] = ordered[index].value + } +} + +func canonicalizeLocation(location *locationResponse, order shared.SourceRefOrder, sourceID string) (int, bool) { + if location == nil { + return 0, false + } + refs := order.Canonicalize(canonicalSourceRefs(location.SourceRefs, sourceID)) + location.SourceRefs = locationResponseRefs(refs) + return order.EarliestValid(refs) +} + +func canonicalLocationList(response extractionResponse, sourceID string) dnd.LocationList { + if response.Locations == nil { + return dnd.LocationList{Locations: nil} + } + locations := make([]dnd.Location, len(response.Locations)) + for index, location := range response.Locations { + refs := canonicalSourceRefs(location.SourceRefs, sourceID) + locations[index] = dnd.Location{ + ID: identity.DeriveID(location.Name, refs), + Name: location.Name, + SourceRefs: refs, + } + } + return dnd.LocationList{Locations: locations} +} + +func canonicalSourceRefs(values []locationSourceRefResponse, sourceID string) []source.SourceRef { + if values == nil { + return nil + } + refs := make([]source.SourceRef, len(values)) + for index, value := range values { + refs[index] = source.SourceRef{SourceID: sourceID, StartUnitID: value.StartUnitID, EndUnitID: value.EndUnitID} + } + return refs +} + +func locationResponseRefs(values []source.SourceRef) []locationSourceRefResponse { + if values == nil { + return nil + } + refs := make([]locationSourceRefResponse, len(values)) + for index, value := range values { + refs[index] = locationSourceRefResponse{StartUnitID: value.StartUnitID, EndUnitID: value.EndUnitID} + } + return refs +} diff --git a/internal/modules/dnd/extract/locations/extractor.go b/internal/modules/dnd/extract/locations/extractor.go new file mode 100644 index 0000000..a8e5834 --- /dev/null +++ b/internal/modules/dnd/extract/locations/extractor.go @@ -0,0 +1,152 @@ +// Package locations extracts source-grounded D&D physical location candidates. +package locations + +import ( + "context" + "fmt" + + "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" + "gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/locations/identity" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared" +) + +const ( + Key = "dnd/locations" + mappingPolicy = "dnd.locations.extract_mapping.v1" +) + +var requiredCapabilities = []string{"chunks", "source.transcript"} +var providedCapabilities = []string{"dnd.locations"} + +var referenceSlotDescriptions = shared.ReferenceSlotDescriptions{ + Glossary: "Optional campaign glossary reference material used only for location disambiguation.", + Party: "Optional party roster reference material used only for location disambiguation.", + Players: "Optional player list reference material used only for location disambiguation.", + Roster: "Deprecated alias for party roster reference material used only for location disambiguation.", +} + +func referenceSlots() []contracts.ReferenceSlot { + return shared.ReferenceSlots(referenceSlotDescriptions) +} + +var _ contracts.Extractor[dnd.LocationList] = (*Extractor)(nil) +var _ contracts.ManifestMetadataProvider = (*Extractor)(nil) +var _ pipeline.CheckpointFingerprintProvider = (*Extractor)(nil) + +type Options struct{} + +type Extractor struct { + llm contracts.StructuredLLMClient + promptSHA string + responseSchemaSHA string +} + +func New(llmClient contracts.StructuredLLMClient, _ Options, references ...contracts.ReferenceSet) (*Extractor, error) { + if llmClient == nil { + return nil, extractorErrorf("LLM client must not be nil") + } + if len(references) > 1 { + return nil, extractorErrorf("at most one reference set may be supplied") + } + promptSHA, err := promptAssetMetadata() + if err != nil { + return nil, extractorErrorf("load prompt metadata: %w", err) + } + responseSchema, err := loadResponseSchema() + if err != nil { + return nil, extractorErrorf("load response schema: %w", err) + } + return &Extractor{llm: llmClient, promptSHA: promptSHA, responseSchemaSHA: responseSchema.SHA256}, nil +} + +func (e *Extractor) Key() string { return Key } + +func (e *Extractor) ReferenceSlots() []contracts.ReferenceSlot { return referenceSlots() } + +func (e *Extractor) ManifestMetadata() map[string]any { + if e == nil { + return nil + } + return map[string]any{ + "prompt_id": PromptID, + "prompt_version": SchemaVersion, + "prompt_sha256": e.promptSHA, + "response_schema_key": string(ResponseSchemaKey), + "response_schema_id": ResponseSchemaID, + "response_schema_name": ResponseSchemaName, + "response_schema_version": SchemaVersion, + "response_schema_sha256": e.responseSchemaSHA, + "identity_policy": identity.Policy, + "mapping_policy": mappingPolicy, + } +} + +func (e *Extractor) CheckpointFingerprints() []pipeline.CheckpointFingerprint { + if e == nil { + return nil + } + return []pipeline.CheckpointFingerprint{ + {Name: "prompt", Value: e.promptSHA}, + {Name: "response_schema", Value: e.responseSchemaSHA}, + {Name: "identity_policy", Value: identity.Policy}, + {Name: "mapping_policy", Value: mappingPolicy}, + } +} + +func (e *Extractor) Extract(ctx context.Context, req contracts.TypedExtractionRequest) (contracts.TypedExtractionResult[dnd.LocationList], error) { + if e == nil { + return contracts.TypedExtractionResult[dnd.LocationList]{}, extractorErrorf("extractor must not be nil") + } + if e.llm == nil { + return contracts.TypedExtractionResult[dnd.LocationList]{}, extractorErrorf("LLM client must not be nil") + } + sourceInput, err := shared.PrepareChunkExtraction(ctx, req) + if err != nil { + return contracts.TypedExtractionResult[dnd.LocationList]{}, extractorErrorf("%w", err) + } + order := shared.NewSourceRefOrder(req.Source) + + var response extractionResponse + 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), + }, &response); err != nil { + return contracts.TypedExtractionResult[dnd.LocationList]{}, extractorErrorf("complete structured output: %w", err) + } + canonicalizeResponse(&response, order, req.Source.ID) + return contracts.TypedExtractionResult[dnd.LocationList]{Value: canonicalLocationList(response, req.Source.ID)}, nil +} + +func ModuleSpec() pipeline.ModuleSpec { + return pipeline.ModuleSpec{ + Key: Key, Stage: pipeline.StageExtract, ExecutionClass: contracts.ExecutionClassLLMBacked, + Requires: append([]string(nil), requiredCapabilities...), Provides: append([]string(nil), providedCapabilities...), + ArtifactKind: dnd.LocationListKind, ReferenceSlots: referenceSlots(), + } +} + +func Register(registry *pipeline.ExtractorRegistry) error { + return pipeline.RegisterExtractorBuilder(registry, ModuleSpec(), validateOptions, func(request pipeline.BuildRequest) (contracts.Extractor[dnd.LocationList], error) { + options, err := DecodeOptions(request.Options) + if err != nil { + return nil, err + } + return New(request.Dependencies.LLM, 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 locations extractor: "+format, args...) +} diff --git a/internal/modules/dnd/extract/locations/extractor_test.go b/internal/modules/dnd/extract/locations/extractor_test.go new file mode 100644 index 0000000..b2c187a --- /dev/null +++ b/internal/modules/dnd/extract/locations/extractor_test.go @@ -0,0 +1,125 @@ +package locations + +import ( + "context" + "errors" + "reflect" + "strings" + "testing" + + "gitea.maximumdirect.net/eric/notarius/internal/core/source" + "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/locations/identity" +) + +func TestExtractMapsLocationsWithOwnedEvidenceAndDeterministicOrder(t *testing.T) { + client := &fakeLocationsLLMClient{response: extractionResponse{Locations: []locationResponse{ + {Name: "The Tavern", SourceRefs: responseSourceRefs(3, 3)}, + {Name: "Old Mill", SourceRefs: []locationSourceRefResponse{{StartUnitID: 2, EndUnitID: 2}, {StartUnitID: 1, EndUnitID: 1}, {StartUnitID: 1, EndUnitID: 1}}}, + }}} + result, err := newExtractor(t, client).Extract(context.Background(), extractionRequest()) + if err != nil { + t.Fatalf("Extract() error = %v, want nil", err) + } + refs := []source.SourceRef{{SourceID: "session-locations", StartUnitID: 1, EndUnitID: 1}, {SourceID: "session-locations", StartUnitID: 2, EndUnitID: 2}} + want := dnd.LocationList{Locations: []dnd.Location{ + {ID: identity.DeriveID("Old Mill", refs), Name: "Old Mill", SourceRefs: refs}, + {ID: identity.DeriveID("The Tavern", []source.SourceRef{{SourceID: "session-locations", StartUnitID: 3, EndUnitID: 3}}), Name: "The Tavern", SourceRefs: []source.SourceRef{{SourceID: "session-locations", StartUnitID: 3, EndUnitID: 3}}}, + }} + if !reflect.DeepEqual(result.Value, want) { + t.Fatalf("Value = %#v, want %#v", result.Value, want) + } + result.Value.Locations[0].SourceRefs[0].StartUnitID = 99 + for _, location := range client.response.Locations { + for _, ref := range location.SourceRefs { + if ref.StartUnitID == 99 { + t.Fatal("result source references alias the model response") + } + } + } +} + +func TestExtractRetainsSameNameLocationsAtDifferentAnchors(t *testing.T) { + client := &fakeLocationsLLMClient{response: extractionResponse{Locations: []locationResponse{ + {Name: "the tavern", SourceRefs: responseSourceRefs(1, 1)}, + {Name: "the tavern", SourceRefs: responseSourceRefs(3, 3)}, + }}} + result, err := newExtractor(t, client).Extract(context.Background(), extractionRequest()) + if err != nil || len(result.Value.Locations) != 2 { + t.Fatalf("Extract() = %#v, %v; want both same-name candidates", result, err) + } + if result.Value.Locations[0].ID == result.Value.Locations[1].ID || result.Value.Locations[0].Name != result.Value.Locations[1].Name { + t.Fatalf("locations = %#v, want distinct evidence-anchored IDs", result.Value.Locations) + } +} + +func TestExtractPreservesInvalidCandidatesForValidators(t *testing.T) { + client := &fakeLocationsLLMClient{content: []byte(`{"locations":[{"name":"","source_refs":[{"start_unit_id":0,"end_unit_id":-1}]}]}`)} + result, err := newExtractor(t, client).Extract(context.Background(), extractionRequest()) + if err != nil { + t.Fatalf("Extract() error = %v, want nil", err) + } + location := result.Value.Locations[0] + if location.ID != "" || location.Name != "" || !reflect.DeepEqual(location.SourceRefs, []source.SourceRef{{SourceID: "session-locations", StartUnitID: 0, EndUnitID: -1}}) { + t.Fatalf("location = %#v, want invalid candidate preserved", location) + } +} + +func TestExtractPassesReferencesWithoutTreatingThemAsEvidence(t *testing.T) { + client := &fakeLocationsLLMClient{response: extractionResponse{Locations: []locationResponse{}}} + req := extractionRequest() + req.References = contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{ + "glossary": {Slot: contracts.ReferenceSlot{Name: "glossary"}, Items: []contracts.ReferenceItem{{SlotName: "glossary", Content: []byte("Old Mill: abandoned granary")}}}, + }} + if _, err := newExtractor(t, client).Extract(context.Background(), req); err != nil { + t.Fatalf("Extract() error = %v", err) + } + inputs := client.requests[0].Inputs + if string(inputs["glossary"].Content) != "Old Mill: abandoned granary" || strings.Contains(string(inputs["transcript"].Content), "abandoned granary") { + t.Fatalf("prompt inputs = %#v, want separated reference material", inputs) + } +} + +func TestExtractDoesNotMutateRequestMaterials(t *testing.T) { + client := &fakeLocationsLLMClient{response: extractionResponse{Locations: []locationResponse{{Name: "Old Mill", SourceRefs: responseSourceRefs(1, 1)}}}} + req := extractionRequest() + beforeUnits := append([]source.SourceUnit(nil), req.Source.Units...) + beforeChunkUnits := append([]source.SourceUnit(nil), req.Chunk.Units...) + beforeContent := append([]byte(nil), req.Chunk.Content...) + if _, err := newExtractor(t, client).Extract(context.Background(), req); err != nil { + t.Fatalf("Extract() error = %v", err) + } + if !reflect.DeepEqual(req.Source.Units, beforeUnits) || !reflect.DeepEqual(req.Chunk.Units, beforeChunkUnits) || !reflect.DeepEqual(req.Chunk.Content, beforeContent) { + t.Fatalf("Extract() mutated request: %#v", req) + } +} + +func TestExtractHandlesEmptyOutputAndLocalFailures(t *testing.T) { + empty, err := newExtractor(t, &fakeLocationsLLMClient{response: extractionResponse{Locations: []locationResponse{}}}).Extract(context.Background(), extractionRequest()) + if err != nil || empty.Value.Locations == nil || len(empty.Value.Locations) != 0 { + t.Fatalf("empty Extract() = %#v, %v; want empty list", empty, err) + } + request := extractionRequest() + var nilExtractor *Extractor + for _, test := range []struct { + name string + extractor *Extractor + req contracts.TypedExtractionRequest + want string + }{ + {name: "nil extractor", extractor: nilExtractor, req: request, want: "extractor"}, + {name: "nil client", extractor: &Extractor{}, req: request, want: "LLM client"}, + {name: "preflight", extractor: newExtractor(t, &fakeLocationsLLMClient{}), req: mismatchedSourceInputRequest(request), want: "must match chunk"}, + } { + t.Run(test.name, func(t *testing.T) { + if _, err := test.extractor.Extract(context.Background(), test.req); err == nil || !strings.Contains(err.Error(), "dnd locations") || !strings.Contains(err.Error(), test.want) { + t.Fatalf("Extract() error = %v, want local context", err) + } + }) + } + _, err = newExtractor(t, &fakeLocationsLLMClient{err: errors.New("provider unavailable")}).Extract(context.Background(), request) + if err == nil || !strings.Contains(err.Error(), "dnd locations") || !strings.Contains(err.Error(), "provider unavailable") { + t.Fatalf("provider error = %v, want contextual provider error", err) + } +} diff --git a/internal/modules/dnd/extract/locations/model.go b/internal/modules/dnd/extract/locations/model.go new file mode 100644 index 0000000..1ad7ff5 --- /dev/null +++ b/internal/modules/dnd/extract/locations/model.go @@ -0,0 +1,15 @@ +package locations + +type extractionResponse struct { + Locations []locationResponse `json:"locations"` +} + +type locationResponse struct { + Name string `json:"name"` + SourceRefs []locationSourceRefResponse `json:"source_refs"` +} + +type locationSourceRefResponse struct { + StartUnitID int `json:"start_unit_id"` + EndUnitID int `json:"end_unit_id"` +} diff --git a/internal/modules/dnd/extract/locations/prompt_assets.go b/internal/modules/dnd/extract/locations/prompt_assets.go new file mode 100644 index 0000000..18a360e --- /dev/null +++ b/internal/modules/dnd/extract/locations/prompt_assets.go @@ -0,0 +1,52 @@ +package locations + +import ( + "fmt" + "sync" + + "gitea.maximumdirect.net/eric/notarius/internal/framework/llm" + "gitea.maximumdirect.net/eric/notarius/internal/framework/promptfs" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared" +) + +const promptAssetRoot = "assets/prompts" + +var promptAssetManifest = shared.PromptAssetManifest{ + ModuleDir: PromptID, + ModuleFiles: []promptfs.ModulePromptFile{ + {Name: "dnd.locations.yaml", Path: "assets/prompts/dnd.locations.yaml"}, + {Name: "task.md", Path: "assets/prompts/task.md"}, + {Name: "instructions.md", Path: "assets/prompts/instructions.md"}, + }, + SharedFiles: []string{ + "common-dnd-system.md", + "common-dnd-extraction-evidence.md", + "common-dnd-identity.md", + "common-dnd-transcript.md", + "common-dnd-references.md", + }, +} + +func RegisterPromptAssets(registry *llm.AssetRegistry) error { + promptFS, err := promptAssetManifest.PromptFS(embeddedAssets) + if err != nil { + return fmt.Errorf("prepare location prompt assets: %w", err) + } + if err := registry.RegisterPromptFS(promptFS, promptAssetRoot); err != nil { + return err + } + return registry.RegisterSchemaFS(embeddedAssets, "assets/schemas") +} + +func promptAssetMetadata() (string, error) { + promptAssetHashOnce.Do(func() { + promptAssetHash, promptAssetHashErr = promptAssetManifest.Hash(embeddedAssets) + }) + return promptAssetHash, promptAssetHashErr +} + +var ( + promptAssetHashOnce sync.Once + promptAssetHash string + promptAssetHashErr error +) diff --git a/internal/modules/dnd/extract/locations/prompt_assets_test.go b/internal/modules/dnd/extract/locations/prompt_assets_test.go new file mode 100644 index 0000000..a81ca56 --- /dev/null +++ b/internal/modules/dnd/extract/locations/prompt_assets_test.go @@ -0,0 +1,50 @@ +package locations + +import ( + "context" + "slices" + "strings" + "testing" + "time" + + "gitea.maximumdirect.net/eric/notarius/internal/framework/llm" + "gitea.maximumdirect.net/eric/promptkit" +) + +func TestRegisterPromptAssetsPreparesLocationPrompt(t *testing.T) { + for _, name := range []string{"common-dnd-system.md", "common-dnd-identity.md", "common-dnd-references.md", "common-dnd-transcript.md", "common-dnd-extraction-evidence.md"} { + if !slices.Contains(promptAssetManifest.SharedFiles, name) { + t.Fatalf("shared prompt assets = %#v, missing %q", promptAssetManifest.SharedFiles, name) + } + } + registry := llm.NewAssetRegistry() + if err := RegisterPromptAssets(registry); err != nil { + t.Fatalf("RegisterPromptAssets() error = %v", err) + } + options, err := registry.PromptKitOptions() + if err != nil { + t.Fatalf("PromptKitOptions() error = %v", err) + } + options = append(options, promptkit.WithProfiles(promptkit.OpenAICompatibleProfile(promptkit.OpenAICompatibleProfileConfig{ID: "location-test-profile", Endpoint: "http://127.0.0.1:1/v1", Model: "location-test-model"}))) + engine, err := promptkit.NewEngine(promptkit.Config{Timeout: time.Second}, options...) + if err != nil { + t.Fatalf("NewEngine() error = %v", err) + } + prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{PromptID: PromptID, PromptVersion: SchemaVersion, ProfileID: "location-test-profile", Inputs: map[string]promptkit.ArtifactRef{ + "transcript": promptkit.Inline(`{"units":[1]}`), "players": promptkit.Inline(" "), "party": promptkit.Inline(" "), "glossary": promptkit.Inline(" "), + }}) + if err != nil { + t.Fatalf("Prepare() error = %v", err) + } + if prepared.OutputContract.SchemaPath != "dnd_locations_llm.v1.json" { + t.Fatalf("output contract = %#v", prepared.OutputContract) + } + if len(prepared.Messages) != 7 || !strings.Contains(prepared.Messages[3].Content, `"units"`) || strings.Contains(prepared.Messages[3].Content, "location-test") { + t.Fatalf("prepared messages = %#v, want rendered transcript only in transcript message", prepared.Messages) + } + for _, index := range []int{2, 3, 6} { + if prepared.Messages[index].CacheControl == nil || prepared.Messages[index].CacheControl.Type != promptkit.CacheControlEphemeral { + t.Fatalf("message %d cache control = %#v, want ephemeral", index, prepared.Messages[index].CacheControl) + } + } +} diff --git a/internal/modules/dnd/extract/locations/registry_test.go b/internal/modules/dnd/extract/locations/registry_test.go new file mode 100644 index 0000000..45899c1 --- /dev/null +++ b/internal/modules/dnd/extract/locations/registry_test.go @@ -0,0 +1,53 @@ +package locations + +import ( + "reflect" + "strings" + "testing" + + "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" + "gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd" + "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/locations/identity" +) + +func TestModuleRegistrationAndMetadata(t *testing.T) { + if _, err := New(nil, Options{}); err == nil || !strings.Contains(err.Error(), "LLM client") { + t.Fatalf("New(nil) error = %v, want client rejection", err) + } + if _, err := New(&fakeLocationsLLMClient{}, Options{}, contracts.ReferenceSet{}, contracts.ReferenceSet{}); err == nil || !strings.Contains(err.Error(), "at most one") { + t.Fatalf("New() error = %v, want reference-set rejection", err) + } + want := pipeline.ModuleSpec{Key: Key, Stage: pipeline.StageExtract, ExecutionClass: contracts.ExecutionClassLLMBacked, Requires: []string{"chunks", "source.transcript"}, Provides: []string{"dnd.locations"}, ArtifactKind: dnd.LocationListKind, ReferenceSlots: referenceSlots()} + if got := ModuleSpec(); !reflect.DeepEqual(got, want) { + t.Fatalf("ModuleSpec() = %#v, want %#v", got, want) + } + registry := pipeline.NewExtractorRegistry() + if err := Register(registry); err != nil { + t.Fatalf("Register() error = %v", err) + } + if got, ok := registry.Spec(Key); !ok || !reflect.DeepEqual(got, want) { + t.Fatalf("registry spec = %#v, present = %t", got, ok) + } + if err := Register(nil); err == nil || !strings.Contains(err.Error(), "extractor registry") { + t.Fatalf("Register(nil) error = %v, want registry rejection", err) + } + if _, err := DecodeOptions(map[string]any{"unknown": true}); err == nil { + t.Fatal("DecodeOptions() accepted unknown option") + } + extractor := newExtractor(t, &fakeLocationsLLMClient{}) + metadata := extractor.ManifestMetadata() + for key, value := range map[string]string{ + "prompt_id": PromptID, "prompt_version": SchemaVersion, + "response_schema_key": string(ResponseSchemaKey), "response_schema_id": ResponseSchemaID, + "response_schema_name": ResponseSchemaName, "response_schema_version": SchemaVersion, + "identity_policy": identity.Policy, "mapping_policy": mappingPolicy, + } { + if metadata[key] != value { + t.Fatalf("metadata[%q] = %#v, want %q", key, metadata[key], value) + } + } + if got := extractor.CheckpointFingerprints(); len(got) != 4 || got[0].Name != "prompt" || got[1].Name != "response_schema" || got[2].Value != identity.Policy || got[3].Value != mappingPolicy { + t.Fatalf("CheckpointFingerprints() = %#v", got) + } +} diff --git a/internal/modules/dnd/extract/locations/schema.go b/internal/modules/dnd/extract/locations/schema.go new file mode 100644 index 0000000..a6529d8 --- /dev/null +++ b/internal/modules/dnd/extract/locations/schema.go @@ -0,0 +1,21 @@ +package locations + +import "gitea.maximumdirect.net/eric/notarius/internal/framework/llm" + +const ( + PromptID = "dnd.locations" + ResponseSchemaKey = llm.ResponseSchemaKey("dnd_locations_llm") + ResponseSchemaID = "notarius.dnd.locations.llm" + ResponseSchemaName = "notarius_dnd_locations_llm_v1" + SchemaVersion = "v1" +) + +func loadResponseSchema() (llm.ResponseSchema, error) { + return llm.LoadResponseSchema(embeddedAssets, llm.ResponseSchemaDefinition{ + Key: ResponseSchemaKey, + ID: ResponseSchemaID, + Version: SchemaVersion, + Name: ResponseSchemaName, + AssetPath: "assets/schemas/dnd_locations_llm.v1.json", + }) +} diff --git a/internal/modules/dnd/extract/locations/schema_test.go b/internal/modules/dnd/extract/locations/schema_test.go new file mode 100644 index 0000000..dd1c532 --- /dev/null +++ b/internal/modules/dnd/extract/locations/schema_test.go @@ -0,0 +1,25 @@ +package locations + +import ( + "encoding/json" + "strings" + "testing" +) + +func TestLocationResponseSchemaIsPrivateAndStructural(t *testing.T) { + schema, err := loadResponseSchema() + if err != nil { + t.Fatalf("loadResponseSchema() error = %v", err) + } + if schema.Key != ResponseSchemaKey || schema.ID != ResponseSchemaID || schema.Name != ResponseSchemaName || schema.Version != SchemaVersion || !strings.HasPrefix(schema.SHA256, "sha256:") || !json.Valid(schema.JSONSchema) { + t.Fatalf("schema = %#v, want location response schema", schema) + } + var document map[string]any + if err := json.Unmarshal(schema.JSONSchema, &document); err != nil { + t.Fatal(err) + } + encoded, err := json.Marshal(document) + if err != nil || strings.Contains(string(encoded), `"id"`) { + t.Fatalf("schema = %s, want no durable ID field", encoded) + } +} diff --git a/internal/modules/dnd/extract/locations/test_helpers_test.go b/internal/modules/dnd/extract/locations/test_helpers_test.go new file mode 100644 index 0000000..41631ed --- /dev/null +++ b/internal/modules/dnd/extract/locations/test_helpers_test.go @@ -0,0 +1,89 @@ +package locations + +import ( + "context" + "encoding/json" + "errors" + "testing" + + "gitea.maximumdirect.net/eric/notarius/internal/core/source" + "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" +) + +func extractionRequest() contracts.TypedExtractionRequest { + doc := sourceDocument() + chunk := &source.Chunk{ + ID: "session-locations:chunk:0", SourceID: doc.ID, Index: 0, + Ref: source.SourceRef{SourceID: doc.ID, StartUnitID: 1, EndUnitID: 3}, + Content: []byte(`{"units":[1,2,3]}`), MediaType: "application/json", + Units: append([]source.SourceUnit(nil), doc.Units...), + } + return contracts.TypedExtractionRequest{ + Source: doc, Chunk: chunk, + SourceInput: contracts.NewLLMInputMaterial("source", chunk.MediaType, chunk.Content, "sha256:chunk", "file:///session-locations.json"), + SessionID: "location-session", LLMProfile: "location-profile", + } +} + +func sourceDocument() *source.SourceDocument { + return &source.SourceDocument{ID: "session-locations", Kind: "transcript", Format: "application/json", Digest: "sha256:test", Units: []source.SourceUnit{ + {ID: 1, Kind: "transcript_segment", Text: "The party enters the Old Mill."}, + {ID: 2, Kind: "transcript_segment", Text: "They leave the old road behind."}, + {ID: 3, Kind: "transcript_segment", Text: "The tavern is quiet."}, + }} +} + +func responseSourceRefs(startUnitID, endUnitID int) []locationSourceRefResponse { + return []locationSourceRefResponse{{StartUnitID: startUnitID, EndUnitID: endUnitID}} +} + +func newExtractor(t *testing.T, client contracts.StructuredLLMClient, references ...contracts.ReferenceSet) *Extractor { + t.Helper() + extractor, err := New(client, Options{}, references...) + if err != nil { + t.Fatalf("New() error = %v, want nil", err) + } + return extractor +} + +func mismatchedSourceInputRequest(req contracts.TypedExtractionRequest) contracts.TypedExtractionRequest { + req.SourceInput = contracts.NewLLMInputMaterial("source", "application/json", []byte(`{"different":true}`), "sha256:other", "file:///other.json") + return req +} + +type fakeLocationsLLMClient struct { + response extractionResponse + content []byte + err error + requests []contracts.StructuredCompletionRequest +} + +func (client *fakeLocationsLLMClient) CompleteStructured(_ context.Context, req contracts.StructuredCompletionRequest, out any) (contracts.StructuredCompletionResponse, error) { + client.requests = append(client.requests, cloneStructuredCompletionRequest(req)) + if client.err != nil { + return contracts.StructuredCompletionResponse{}, client.err + } + target, ok := out.(*extractionResponse) + if !ok { + return contracts.StructuredCompletionResponse{}, errors.New("unexpected output target") + } + content := append([]byte(nil), client.content...) + if len(content) != 0 { + if err := json.Unmarshal(content, target); err != nil { + return contracts.StructuredCompletionResponse{}, err + } + } else { + *target = client.response + var err error + content, err = json.Marshal(client.response) + if err != nil { + return contracts.StructuredCompletionResponse{}, err + } + } + return contracts.StructuredCompletionResponse{Content: content}, nil +} + +func cloneStructuredCompletionRequest(req contracts.StructuredCompletionRequest) contracts.StructuredCompletionRequest { + req.Inputs = req.Inputs.Clone() + return req +}