Files
notarius/internal/modules/dnd/chunk/scenes/chunker.go

217 lines
7.6 KiB
Go
Raw Normal View History

2026-07-04 13:02:02 +00:00
package scenes
import (
"context"
"encoding/json"
2026-07-04 13:02:02 +00:00
"fmt"
"strings"
"go.maximumdirect.net/promptkit"
2026-07-04 13:02:02 +00:00
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
2026-07-17 05:05:48 +00:00
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
2026-07-04 13:02:02 +00:00
)
const Key = "dnd/scenes"
const PromptID = "notarius/dnd.scenes"
const CorrectionPromptID = "notarius/dnd.scenes.repair"
2026-07-04 13:02:02 +00:00
var requiredCapabilities = []string{
"source.transcript",
}
var providedCapabilities = []string{
"chunks",
}
2026-07-17 05:05:48 +00:00
var referenceSlotDescriptions = shared.ReferenceSlotDescriptions{
Glossary: "Optional campaign glossary reference material used only for scene disambiguation.",
Party: "Optional party roster reference material used only for scene disambiguation.",
Players: "Optional player list reference material used only for scene disambiguation.",
Roster: "Deprecated alias for party roster reference material used only for scene disambiguation.",
}
2026-07-04 13:02:02 +00:00
var _ contracts.Chunker = (*Chunker)(nil)
type Options struct{}
2026-07-04 13:02:02 +00:00
type Chunker struct {
engine *promptkit.Engine
}
func New(engine *promptkit.Engine, _ Options) (*Chunker, error) {
if engine == nil {
return nil, chunkerErrorf("native engine must not be nil")
}
return &Chunker{engine: engine}, nil
2026-07-04 13:02:02 +00:00
}
func (c *Chunker) Key() string {
return Key
}
func (c *Chunker) ReferenceSlots() []contracts.ReferenceSlot {
2026-07-17 05:05:48 +00:00
return shared.ReferenceSlots(referenceSlotDescriptions)
}
func (c *Chunker) Plan(ctx context.Context, req contracts.ChunkRequest) (contracts.ChunkPlanResult, error) {
2026-07-04 13:02:02 +00:00
if c == nil {
return contracts.ChunkPlanResult{}, chunkerErrorf("chunker must not be nil")
2026-07-04 13:02:02 +00:00
}
if c.engine == nil {
return contracts.ChunkPlanResult{}, chunkerErrorf("native engine must not be nil")
}
2026-07-04 13:02:02 +00:00
if ctx == nil {
return contracts.ChunkPlanResult{}, chunkerErrorf("context must not be nil")
2026-07-04 13:02:02 +00:00
}
if err := ctx.Err(); err != nil {
return contracts.ChunkPlanResult{}, chunkerErrorf("context error before chunking: %w", err)
2026-07-04 13:02:02 +00:00
}
if req.Source == nil {
return contracts.ChunkPlanResult{}, chunkerErrorf("source must not be nil")
2026-07-04 13:02:02 +00:00
}
if len(req.Source.Units) == 0 {
return contracts.ChunkPlanResult{}, chunkerErrorf("source units must not be empty")
2026-07-04 13:02:02 +00:00
}
if err := source.ValidateDocument(req.Source); err != nil {
return contracts.ChunkPlanResult{}, chunkerErrorf("validate source document: %w", err)
2026-07-04 13:02:02 +00:00
}
materials := shared.PromptInputs(req.SourceInput, req.References)
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}
plan, outcome, err := pipeline.RunProducer(ctx, c.engine, req.Operation, initial,
func(_ context.Context, result *promptkit.RunResult) (*source.ChunkPlan, []string, error) {
var response chunkResponse
if err := json.Unmarshal([]byte(result.RawOutput), &response); err != nil {
return nil, nil, chunkerErrorf("decode native output: %w", err)
}
plan, err := planFromResponse(req.Source, response)
if err != nil {
return nil, []string{fmt.Sprintf("Revise the scene boundaries: %v. Use source-unit IDs from the supplied transcript and cover every unit in document order, without gaps or overlaps.", err)}, nil
}
return &plan, 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, *source.ChunkPlan) (source.ChunkPlan, error) {
plan := source.ChunkPlan{SourceDigest: req.Source.Digest, Ranges: []source.ChunkRange{{
StartUnitID: req.Source.Units[0].ID, EndUnitID: req.Source.Units[len(req.Source.Units)-1].ID,
}}}
if _, err := source.MaterializeChunkPlan(req.Source, plan); err != nil {
return source.ChunkPlan{}, chunkerErrorf("materialize whole-source fallback: %w", err)
}
return plan, nil
})
2026-07-04 13:02:02 +00:00
if err != nil {
return contracts.ChunkPlanResult{}, chunkerErrorf("produce scene plan: %w", err)
2026-07-04 13:02:02 +00:00
}
return contracts.ChunkPlanResult{Plan: plan, Outcome: outcome}, nil
2026-07-04 13:02:02 +00:00
}
func ModuleSpec() pipeline.ModuleSpec {
return pipeline.ModuleSpec{
Key: Key,
Stage: pipeline.StageChunk,
ExecutionClass: contracts.ExecutionClassLLMBacked,
Prompts: []string{PromptID, CorrectionPromptID},
Requires: append([]string(nil), requiredCapabilities...),
Provides: append([]string(nil), providedCapabilities...),
ReferenceSlots: shared.ReferenceSlots(referenceSlotDescriptions),
2026-07-04 13:02:02 +00:00
}
}
func Register(registry *pipeline.ChunkerRegistry) error {
return registry.RegisterBuilderWithSpec(ModuleSpec(), validateOptions, func(request pipeline.BuildRequest) (contracts.Chunker, error) {
options, err := DecodeOptions(request.Options)
if err != nil {
return nil, err
}
return New(request.Dependencies.Engine, options)
2026-07-04 13:02:02 +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{}, chunkerErrorf("%w", err)
}
return Options{}, nil
}
2026-07-24 00:35:10 +00:00
func planFromResponse(doc *source.SourceDocument, response chunkResponse) (source.ChunkPlan, error) {
2026-07-04 13:02:02 +00:00
if response.Scenes == nil {
return source.ChunkPlan{}, fmt.Errorf("scenes must be present")
2026-07-04 13:02:02 +00:00
}
if len(response.Scenes) == 0 {
return source.ChunkPlan{}, fmt.Errorf("scenes must not be empty")
2026-07-04 13:02:02 +00:00
}
index := source.NewDocumentIndex(doc)
2026-07-04 13:02:02 +00:00
ranges := make([]source.ChunkRange, 0, len(response.Scenes))
2026-07-04 13:02:02 +00:00
previousEnd := -1
for i, scene := range response.Scenes {
startUnitID, err := shared.ResolveUnitID(index, "start_unit_id", scene.StartUnitID)
2026-07-04 13:02:02 +00:00
if err != nil {
2026-07-24 00:35:10 +00:00
return source.ChunkPlan{}, fmt.Errorf("scene[%d] %w", i, err)
}
endUnitID, err := shared.ResolveUnitID(index, "end_unit_id", scene.EndUnitID)
2026-07-24 00:35:10 +00:00
if err != nil {
return source.ChunkPlan{}, fmt.Errorf("scene[%d] %w", i, err)
2026-07-04 13:02:02 +00:00
}
startIndex, ok := index.Position(startUnitID)
2026-07-04 13:02:02 +00:00
if !ok {
2026-07-24 00:35:10 +00:00
return source.ChunkPlan{}, fmt.Errorf("scene[%d] start_unit_id %d was not found", i, startUnitID)
2026-07-04 13:02:02 +00:00
}
endIndex, ok := index.Position(endUnitID)
2026-07-04 13:02:02 +00:00
if !ok {
2026-07-24 00:35:10 +00:00
return source.ChunkPlan{}, fmt.Errorf("scene[%d] end_unit_id %d was not found", i, endUnitID)
2026-07-04 13:02:02 +00:00
}
if startIndex > endIndex {
2026-07-24 00:35:10 +00:00
return source.ChunkPlan{}, fmt.Errorf("scene[%d] start_unit_id %d appears after end_unit_id %d", i, startUnitID, endUnitID)
2026-07-04 13:02:02 +00:00
}
if i == 0 && startIndex != 0 {
return source.ChunkPlan{}, fmt.Errorf("first scene must start at first source unit %d", doc.Units[0].ID)
2026-07-04 13:02:02 +00:00
}
if i > 0 {
if startIndex <= previousEnd {
return source.ChunkPlan{}, fmt.Errorf("scene[%d] overlaps previous scene", i)
2026-07-04 13:02:02 +00:00
}
if startIndex > previousEnd+1 {
return source.ChunkPlan{}, fmt.Errorf("scene[%d] leaves a gap after previous scene", i)
2026-07-04 13:02:02 +00:00
}
}
previousEnd = endIndex
ranges = append(ranges, source.ChunkRange{
2026-07-24 00:35:10 +00:00
StartUnitID: startUnitID,
EndUnitID: endUnitID,
2026-07-04 13:02:02 +00:00
})
}
if previousEnd != len(doc.Units)-1 {
return source.ChunkPlan{}, fmt.Errorf("final scene must end at final source unit %d", doc.Units[len(doc.Units)-1].ID)
2026-07-04 13:02:02 +00:00
}
return source.ChunkPlan{
SourceDigest: doc.Digest,
Ranges: ranges,
}, nil
}
2026-07-04 13:02:02 +00:00
func chunkerErrorf(format string, args ...any) error {
return fmt.Errorf("dnd scenes chunker: "+format, args...)
}