Configure built-in retries across execution paths

engine.go

@@ -62,14 +62,18 @@ var (
 	// available through errors.Is.
 	ErrLLMGenerate = errors.New("failed to generate output")
 	// ErrTransport identifies a failed HTTP request by the built-in model
-	// client. It also matches ErrLLMGenerate and retains the transport cause
-	// for errors.Is and errors.As. It does not imply that the provider received
-	// no work.
+	// client. Generation errors in this category also match ErrLLMGenerate and
+	// retain the transport cause for errors.Is and errors.As. It does not imply
+	// that the provider received no work.
 	ErrTransport = errors.New("model transport failed")
 	// ErrMalformedResponse identifies an invalid successful model response or
-	// a nil successful response from an injected client. It also matches
-	// ErrLLMGenerate.
+	// a nil successful response from an injected client. Generation errors in
+	// this category also match ErrLLMGenerate.
 	ErrMalformedResponse = errors.New("malformed model response")
+	// ErrRetriesExhausted identifies a built-in generation sequence whose
+	// positive transient retry budget ended with another eligible HTTP status.
+	// RetryExhaustedError retains the final cause and actual attempt count.
+	ErrRetriesExhausted = errors.New("transient model retries exhausted")
 	// ErrValidation identifies an operational failure to load or compile a
 	// schema or validate output. A completed validation whose Status is
 	// ValidationFailed is returned in RunResult without this error.
@@ -113,6 +117,11 @@ type Config struct {
 	// Timeout or the 10-minute default. The supplied client is not mutated. This
 	// field is ignored when WithLLMClient is used.
 	HTTPClient *http.Client
+	// TransientRetries selects additional built-in HTTP attempts after eligible
+	// provider statuses. Nil defaults to two; zero disables retries. Negative
+	// values are invalid. Injected LLMClient implementations are never retried
+	// automatically.
+	TransientRetries *int
 }
 
 // Option customizes engine construction.
@@ -301,7 +310,8 @@ func WithSchemaFile(path string) Option {
 // NewEngine returns an error matching ErrInvalidConfig for invalid
 // configuration, options, or backend-capacity policies. Each constructed
 // Engine has independent backend-capacity pools. Construction does not perform
-// model requests or require credentials.
+// model requests or require credentials. A negative Config.TransientRetries
+// is invalid.
 func NewEngine(cfg Config, opts ...Option) (*Engine, error) {
 	var options engineOptions
 	for _, opt := range opts {
@@ -314,7 +324,7 @@ func NewEngine(cfg Config, opts ...Option) (*Engine, error) {
 	}
 
 	assembled, err := internalengine.New(
-		internalengine.Config{PromptDir: cfg.PromptDir, ProfileDir: cfg.ProfileDir, SchemaDir: cfg.SchemaDir, Timeout: cfg.Timeout, HTTPClient: cfg.HTTPClient},
+		internalengine.Config{PromptDir: cfg.PromptDir, ProfileDir: cfg.ProfileDir, SchemaDir: cfg.SchemaDir, Timeout: cfg.Timeout, HTTPClient: cfg.HTTPClient, TransientRetries: copyIntPtr(cfg.TransientRetries)},
 		options.internal,
 	)
 	if err != nil {
@@ -428,7 +438,7 @@ func (e *Engine) InspectProfile(ctx context.Context, profileID string) (*Profile
 // applicable. Cancellation is passed to the active collaborator and is
 // reported in the applicable operation category; no general errors.Is
 // relationship to ctx.Err is promised. Prepare returns no partial result on
-// error.
+// error. It validates RunRequest.TransientRetries but makes no model attempts.
 func (e *Engine) Prepare(ctx context.Context, req RunRequest) (*PreparedRun, error) {
 	if e == nil || e.internal == nil {
 		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
@@ -461,7 +471,8 @@ func (e *Engine) Prepare(ctx context.Context, req RunRequest) (*PreparedRun, err
 // returns does not invalidate the handle or propagate to RunPrepared.
 // PrepareExecution returns the same error categories as [Engine.Prepare] and
 // returns no handle on error. A nil Engine returns an error matching
-// ErrInvalidConfig.
+// ErrInvalidConfig. The effective transient retry budget is frozen privately
+// for RunPrepared and is absent from Details.
 func (e *Engine) PrepareExecution(ctx context.Context, req RunRequest) (*PreparedExecution, error) {
 	if e == nil || e.internal == nil {
 		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
@@ -491,6 +502,13 @@ func (e *Engine) PrepareExecution(ctx context.Context, req RunRequest) (*Prepare
 // repair attempts. An inability to generate or validate returns an error and
 // no partial result.
 //
+// The built-in client retries eligible provider statuses using the effective
+// Config or request budget. With R additional transient attempts and P repair
+// generations, one run can dispatch at most (R+1)×(P+1) Promptkit-controlled
+// model attempts. Each dispatched attempt receives its own generation and
+// HTTP-client timeout; the caller context governs the full operation.
+// Injected LLMClient implementations are not retried automatically.
+//
 // Run can return every error category documented by [Engine.Prepare], plus
 // ErrCapacityExceeded and ErrLLMGenerate. Built-in HTTP execution failures
 // additionally match ErrTransport; malformed successful responses and nil
@@ -500,8 +518,9 @@ func (e *Engine) PrepareExecution(ctx context.Context, req RunRequest) (*Prepare
 // occurs before artifacts, schemas, rendering, or model generation because the
 // selected backend's admission capacity is full; it does not match
 // ErrInvalidRequest or ErrLLMGenerate. A built-in OpenAI-compatible non-2xx
-// response is discoverable as [GenerationError]. Errors from injected clients
-// remain available through errors.Is. Cancellation while waiting for
+// response is discoverable as [GenerationError]. Eligible-status exhaustion
+// with a positive budget is discoverable as [RetryExhaustedError]. Injected
+// errors remain available through errors.Is. Cancellation while waiting for
 // model-generation capacity matches both ErrLLMGenerate and the context error.
 // Cancellation otherwise follows the active collaborator's documented
 // behavior. A nil Engine returns ErrInvalidConfig. Run returns no partial
@@ -546,9 +565,12 @@ func (e *Engine) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
 // ErrCapacityExceeded. A built-in OpenAI-compatible non-2xx response is
 // discoverable as [GenerationError]. Built-in HTTP execution failures match
 // ErrTransport; malformed successful responses and nil successful injected
-// responses match ErrMalformedResponse. A completed content-validation rejection,
-// including repair exhaustion, is returned in RunResult, not as an operational
-// error. An operational error returns no partial RunResult.
+// responses match ErrMalformedResponse. Positive-budget eligible-status
+// exhaustion is discoverable as [RetryExhaustedError]. A completed
+// content-validation rejection, including repair exhaustion, is returned in
+// RunResult, not as an operational
+// error. RunPrepared uses the retry choice frozen during PrepareExecution. An
+// operational error returns no partial RunResult.
 func (e *Engine) RunPrepared(ctx context.Context, prepared *PreparedExecution) (*RunResult, error) {
 	if e == nil || e.internal == nil {
 		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)