2026-07-04 13:02:02 +00:00
package scenes
import (
"context"
2026-11-22 00:34:33 +00:00
"encoding/json"
2026-07-04 13:02:02 +00:00
"fmt"
2026-11-22 00:34:33 +00:00
"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"
2026-11-22 00:34:33 +00:00
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 {
2026-07-06 17:22:21 +00:00
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-05 18:48:45 -05:00
}
2026-07-04 13:02:02 +00:00
var _ contracts . Chunker = ( * Chunker ) ( nil )
2026-07-17 06:30:56 +00:00
type Options struct { }
2026-07-04 13:02:02 +00:00
2026-07-17 06:30:56 +00:00
type Chunker struct {
2026-11-22 00:34:33 +00:00
engine * promptkit . Engine
2026-07-17 06:30:56 +00:00
}
2026-11-22 00:34:33 +00:00
func New ( engine * promptkit . Engine , _ Options ) ( * Chunker , error ) {
if engine == nil {
return nil , chunkerErrorf ( "native engine must not be nil" )
2026-07-17 06:30:56 +00:00
}
2026-11-22 00:34:33 +00:00
return & Chunker { engine : engine } , nil
2026-07-04 13:02:02 +00:00
}
func ( c * Chunker ) Key ( ) string {
return Key
}
2026-07-05 16:06:47 +00:00
func ( c * Chunker ) ReferenceSlots ( ) [ ] contracts . ReferenceSlot {
2026-07-17 05:05:48 +00:00
return shared . ReferenceSlots ( referenceSlotDescriptions )
2026-07-05 16:06:47 +00:00
}
2026-07-17 23:57:59 +00:00
func ( c * Chunker ) Plan ( ctx context . Context , req contracts . ChunkRequest ) ( contracts . ChunkPlanResult , error ) {
2026-07-04 13:02:02 +00:00
if c == nil {
2026-07-17 23:57:59 +00:00
return contracts . ChunkPlanResult { } , chunkerErrorf ( "chunker must not be nil" )
2026-07-04 13:02:02 +00:00
}
2026-11-22 00:34:33 +00:00
if c . engine == nil {
return contracts . ChunkPlanResult { } , chunkerErrorf ( "native engine must not be nil" )
2026-07-17 06:30:56 +00:00
}
2026-07-04 13:02:02 +00:00
if ctx == nil {
2026-07-17 23:57:59 +00:00
return contracts . ChunkPlanResult { } , chunkerErrorf ( "context must not be nil" )
2026-07-04 13:02:02 +00:00
}
if err := ctx . Err ( ) ; err != nil {
2026-07-17 23:57:59 +00:00
return contracts . ChunkPlanResult { } , chunkerErrorf ( "context error before chunking: %w" , err )
2026-07-04 13:02:02 +00:00
}
if req . Source == nil {
2026-07-17 23:57:59 +00:00
return contracts . ChunkPlanResult { } , chunkerErrorf ( "source must not be nil" )
2026-07-04 13:02:02 +00:00
}
if len ( req . Source . Units ) == 0 {
2026-07-17 23:57:59 +00:00
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 {
2026-07-17 23:57:59 +00:00
return contracts . ChunkPlanResult { } , chunkerErrorf ( "validate source document: %w" , err )
2026-07-04 13:02:02 +00:00
}
2026-11-22 00:34:33 +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 {
2026-11-22 00:34:33 +00:00
return contracts . ChunkPlanResult { } , chunkerErrorf ( "produce scene plan: %w" , err )
2026-07-04 13:02:02 +00:00
}
2026-11-22 00:34:33 +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 {
2026-11-22 00:34:33 +00:00
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 {
2026-07-17 06:30:56 +00:00
return registry . RegisterBuilderWithSpec ( ModuleSpec ( ) , validateOptions , func ( request pipeline . BuildRequest ) ( contracts . Chunker , error ) {
options , err := DecodeOptions ( request . Options )
if err != nil {
return nil , err
}
2026-11-22 00:34:33 +00:00
return New ( request . Dependencies . Engine , options )
2026-07-04 13:02:02 +00:00
} )
}
2026-07-17 06:30:56 +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 {
2026-07-17 23:57:59 +00:00
return source . ChunkPlan { } , fmt . Errorf ( "scenes must be present" )
2026-07-04 13:02:02 +00:00
}
if len ( response . Scenes ) == 0 {
2026-07-17 23:57:59 +00:00
return source . ChunkPlan { } , fmt . Errorf ( "scenes must not be empty" )
2026-07-04 13:02:02 +00:00
}
2026-07-25 13:01:31 +00:00
index := source . NewDocumentIndex ( doc )
2026-07-04 13:02:02 +00:00
2026-07-17 23:57:59 +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 {
2026-07-25 13:01:31 +00:00
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 )
}
2026-07-25 13:01:31 +00:00
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
}
2026-07-25 13:01:31 +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
}
2026-07-25 13:01:31 +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 {
2026-07-17 23:57:59 +00:00
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 {
2026-07-17 23:57:59 +00:00
return source . ChunkPlan { } , fmt . Errorf ( "scene[%d] overlaps previous scene" , i )
2026-07-04 13:02:02 +00:00
}
if startIndex > previousEnd + 1 {
2026-07-17 23:57:59 +00:00
return source . ChunkPlan { } , fmt . Errorf ( "scene[%d] leaves a gap after previous scene" , i )
2026-07-04 13:02:02 +00:00
}
}
previousEnd = endIndex
2026-07-17 23:57:59 +00:00
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 {
2026-07-17 23:57:59 +00:00
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
}
2026-07-17 23:57:59 +00:00
return source . ChunkPlan {
SourceDigest : doc . Digest ,
Ranges : ranges ,
} , nil
2026-07-07 18:34:23 +00:00
}
2026-07-04 13:02:02 +00:00
func chunkerErrorf ( format string , args ... any ) error {
return fmt . Errorf ( "dnd scenes chunker: " + format , args ... )
}