Files
notarius/internal/framework/pipeline/producer.go

311 lines
12 KiB
Go

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
}