package pipeline import ( "context" "errors" "fmt" "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" "go.maximumdirect.net/promptkit" ) // RunProducer connects native execution to typed interpretation and application // assessment. Interpretation returns nil when no typed candidate can be built; // actionable findings remain separate from operational errors. Correction builds // only the next assignment, never conversation history. Fallback receives only // the final usable candidate, or nil after an unusable/failed execution. func RunProducer[T any]( ctx context.Context, engine *promptkit.Engine, operation contracts.ProducerOperation[T], initial promptkit.RunRequest, interpret func(context.Context, *promptkit.RunResult) (*T, []string, error), correct func(context.Context, []string) (promptkit.RunRequest, error), fallback func(context.Context, *T) (T, error), ) (T, contracts.ProducerOutcome, error) { var zero T if ctx == nil { return zero, contracts.ProducerOutcome{}, errors.New("producer context must not be nil") } if err := ctx.Err(); err != nil { return zero, contracts.ProducerOutcome{}, err } if interpret == nil || operation.Assess == nil { return zero, contracts.ProducerOutcome{}, errors.New("producer interpretation and assessment must be supplied") } if operation.Controls.MaxAdditionalTurns < 0 { return zero, contracts.ProducerOutcome{}, fmt.Errorf("%w: additional turns must not be negative", promptkit.ErrInvalidRequest) } var candidate *T var guidance []string var failure error var assessmentError error accepted := false evaluate := func(result *promptkit.RunResult) { candidate, guidance, failure, accepted = nil, nil, nil, false var assessment contracts.CandidateAssessment defer func() { if operation.Execution.Capture == nil || result == nil { return } errorText := "" if failure != nil { errorText = failure.Error() } if err := operation.Execution.RecordEvidence("interpretations/"+result.RunID+".json", map[string]any{ "run_id": result.RunID, "usable_candidate": candidate != nil, "accepted": accepted, "correction_guidance": guidance, "assessment": assessmentEvidence(assessment), "error": errorText, }); err != nil { assessmentError = errors.Join(assessmentError, err) } }() if canceled := ctx.Err(); canceled != nil { failure = canceled return } if result == nil || result.Validation.Status == promptkit.ValidationFailed || !result.Validation.IsValid { failure = fmt.Errorf("%w: producer output did not satisfy its native contract", promptkit.ErrValidation) return } candidate, guidance, failure = interpret(ctx, result) if canceled := ctx.Err(); canceled != nil { failure = canceled return } if failure != nil { var captureErr *contracts.CaptureError if errors.As(failure, &captureErr) { assessmentError = failure } candidate, guidance = nil, nil return } if candidate == nil { failure = errors.New("producer response could not be interpreted as a usable candidate") return } var err error assessment, err = operation.Assess(ctx, *candidate) if err != nil { assessmentError = err return } validatorGuidance, err := assessment.Guidance() if err != nil { assessmentError = err return } guidance = append(guidance, validatorGuidance...) accepted = assessment.Accepted() && len(guidance) == 0 failure = assessment.Err() if !accepted && failure == nil { failure = errors.New("producer candidate requires correction") } } request := producerRequest(initial, operation.Execution, true) request.CaptureExchange = request.CaptureExchange || (correct != nil && operation.Controls.MaxAdditionalTurns > 0) request, capture := CaptureNativeRequest(request, scopeEvidence(operation.Execution.Capture, "initial")) if captureErr := capture.Err(); captureErr != nil { return zero, contracts.ProducerOutcome{}, captureErr } var result *promptkit.RunResult var err error var cacheKey string cache := operation.Cache if captureErr := operation.Execution.RecordEvidence("cache/selection.json", map[string]any{"mode": operation.Controls.Cache, "reuse_eligible": operation.ReuseEligible, "store_available": cache != nil && cache.Store != nil}); captureErr != nil { return zero, contracts.ProducerOutcome{}, captureErr } if cache != nil && operation.Execution.Capture != nil { owned := *cache existing := owned.Observe owned.Observe = func(ctx context.Context, observation contracts.CacheObservation) error { if err := captureCacheObservation(operation.Execution.Capture, observation); err != nil { return err } if existing != nil { return existing(ctx, observation) } return nil } cache = &owned } if cache != nil && cache.Store != nil && operation.ReuseEligible && operation.Controls.Cache != contracts.CacheBypass { if cache.Encode == nil || cache.Decode == nil { return zero, contracts.ProducerOutcome{}, errors.New("producer cache codec must be supplied") } if mode := operation.Controls.Cache; mode != "" && mode != contracts.CacheAuto && mode != contracts.CacheRefresh { return zero, contracts.ProducerOutcome{}, fmt.Errorf("%w: unknown cache mode %q", promptkit.ErrInvalidRequest, mode) } var prepared *promptkit.PreparedExecution prepared, err = engine.PrepareExecution(ctx, request) if err == nil { defer prepared.Discard() details := prepared.Details() if capture != nil { capture.RetainPrepared(copyPreparedEvidence(details)) } cacheKey = details.MessageContentHash if captureErr := observeProducerCache(ctx, cache, contracts.CacheObservation{Decision: "prepared", MessageContentHash: cacheKey, Prepared: &details}); captureErr != nil { return zero, contracts.ProducerOutcome{}, captureFailure(captureErr, capture.Finish(nil, captureErr, false, false)) } reused, lookupErr := lookupProducerCache(ctx, cache, operation.Controls.Cache, cacheKey) if lookupErr != nil { return zero, contracts.ProducerOutcome{}, captureFailure(lookupErr, capture.Finish(nil, lookupErr, false, false)) } if reused != nil { if captureErr := capture.Finish(nil, nil, false, true); captureErr != nil { return zero, contracts.ProducerOutcome{}, captureErr } return *reused, contracts.ProducerOutcome{Disposition: contracts.ProducerAccepted, ReuseEligible: true}, nil } result, err = engine.RunPrepared(ctx, prepared) } } else { if cache != nil { decision := "bypass" if !operation.ReuseEligible { decision = "ineligible" } if err := observeProducerCache(ctx, cache, contracts.CacheObservation{Decision: decision}); err != nil { return zero, contracts.ProducerOutcome{}, captureFailure(err, capture.Finish(nil, err, false, false)) } } result, err = engine.Run(ctx, request) } if captureErr := capture.Finish(result, err, ctx.Err() != nil, false); captureErr != nil { return zero, contracts.ProducerOutcome{}, captureFailure(errors.Join(ctx.Err(), err), captureErr) } if canceled := ctx.Err(); canceled != nil { return zero, contracts.ProducerOutcome{}, canceled } if err != nil { failure = err } else { evaluate(result) } if canceled := ctx.Err(); canceled != nil { return zero, contracts.ProducerOutcome{}, canceled } if assessmentError != nil { return zero, contracts.ProducerOutcome{}, assessmentError } if !accepted && err == nil && len(guidance) > 0 && correct != nil && operation.Controls.MaxAdditionalTurns > 0 { var pendingCapture *NativeCapture var recordingErr error coordination, coordinateErr := engine.Coordinate(ctx, promptkit.CoordinateRequest{ Start: result.Exchange, AdditionalTurns: operation.Controls.MaxAdditionalTurns, Observer: operation.Execution.Observer, Next: func(_ context.Context, turn promptkit.ConversationTurn) (*promptkit.RunRequest, error) { // The first callback has no new result. Its findings already exist. if turn.Result != nil { recordingErr = pendingCapture.Finish(turn.Result, nil, false, false) pendingCapture = nil if recordingErr != nil { return nil, recordingErr } evaluate(turn.Result) } if assessmentError != nil { return nil, assessmentError } if accepted || len(guidance) == 0 || turn.RemainingTurns == 0 { return nil, nil } // Once another execution is selected, an earlier candidate is not a // terminal fallback source if construction or native execution fails. candidate = nil correctionPath := "" if operation.Execution.Capture != nil { correctionPath = "corrections/" + turn.Exchange.Details().RunID recordingErr = operation.Execution.RecordEvidence(correctionPath+"/assignment.json", map[string]any{"guidance": guidance}) if recordingErr != nil { return nil, recordingErr } } next, buildErr := correct(ctx, guidance) if buildErr != nil { if correctionPath != "" { recordingErr = operation.Execution.RecordEvidence(correctionPath+"/construction-failure.json", map[string]any{"error": buildErr.Error()}) } return nil, buildErr } if initial.ProfileID != "" { next.ProfileID = initial.ProfileID } if initial.SessionID != "" { next.SessionID = initial.SessionID } next = producerRequest(next, operation.Execution, false) if operation.Execution.Capture != nil { next, pendingCapture = CaptureNativeRequest(next, scopeEvidence(operation.Execution.Capture, correctionPath)) if recordingErr = pendingCapture.Err(); recordingErr != nil { return nil, recordingErr } } return &next, nil }, }) if pendingCapture != nil { recordingErr = errors.Join(recordingErr, pendingCapture.Finish(coordination.Undelivered, coordinateErr, coordination.Undelivered != nil, false)) } if recordingErr != nil { return zero, contracts.ProducerOutcome{}, captureFailure(coordinateErr, recordingErr) } if canceled := ctx.Err(); canceled != nil { return zero, contracts.ProducerOutcome{}, canceled } if coordination.Undelivered != nil { if coordinateErr == nil { coordinateErr = errors.New("native continuation response was not delivered") } return zero, contracts.ProducerOutcome{}, coordinateErr } if assessmentError != nil { return zero, contracts.ProducerOutcome{}, assessmentError } if coordinateErr != nil { candidate, failure, accepted = nil, coordinateErr, false } } if accepted { if cacheKey != "" { if err := storeProducerCache(ctx, cache, operation.Controls.Cache, cacheKey, *candidate); err != nil { return zero, contracts.ProducerOutcome{}, err } } return *candidate, contracts.ProducerOutcome{Disposition: contracts.ProducerAccepted, ReuseEligible: operation.ReuseEligible}, nil } var construct func(context.Context) (T, error) if fallback != nil { construct = func(ctx context.Context) (T, error) { return fallback(ctx, candidate) } } return FinishProducerFailure(ctx, operation.Controls.Mode, failure, construct) } // producerRequest applies native options to a value copy. The invocation // observer is enrolled here for the initial run and on CoordinateRequest for // continuations, never twice on the same continuation. func producerRequest(request promptkit.RunRequest, options contracts.ExecutionOptions, initial bool) promptkit.RunRequest { if options.Execution != nil { request.Execution = options.Execution } if options.TransientRetries != nil { request.TransientRetries = options.TransientRetries } if initial { request.Observer = promptkit.ComposeObservers(request.Observer, options.Observer) } if options.OnPrepared != nil { existing := request.OnPrepared request.OnPrepared = func(ctx context.Context, details promptkit.PreparedRun) { if existing != nil { existing(ctx, details) } options.OnPrepared(ctx, details) } } return request }