execution

package
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 11, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

Documentation

Overview

Package execution owns attempt state, retry and fallback budgets, and the response-byte commitment boundary for inference execution.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrPlanRequired reports a missing route plan.
	ErrPlanRequired = errors.New("route plan is required")
	// ErrAttemptRequired reports a missing provider attempt function.
	ErrAttemptRequired = errors.New("provider attempt function is required")
	// ErrAttemptBudget reports exhaustion of the total logical-attempt budget.
	ErrAttemptBudget = errors.New("logical attempt budget exhausted")
	// ErrElapsedBudget reports exhaustion of the total elapsed-time budget.
	ErrElapsedBudget = errors.New("execution elapsed-time budget exhausted")
	// ErrAllAttemptsFailed reports that no planned route completed.
	ErrAllAttemptsFailed = errors.New("all planned attempts failed")
)

Functions

func CanFallback

func CanFallback(providerFailure *failure.Failure) bool

CanFallback reports whether policy can move to the next planned route.

func IsStreamTerminal

func IsStreamTerminal(err error) bool

IsStreamTerminal reports stream completion without treating it as failure.

func RecordCredential added in v1.0.3

func RecordCredential(ctx context.Context, evidence CredentialEvidence)

RecordCredential binds secret-free selection evidence to the current provider attempt. Calls outside an executor-owned attempt are ignored.

func RecordCredentialAccepted added in v1.0.3

func RecordCredentialAccepted(ctx context.Context)

RecordCredentialAccepted records that the provider accepted the selected material far enough to return a provider response or stream.

func WithAttemptAction added in v1.0.2

func WithAttemptAction(err error, action AttemptAction) error

WithAttemptAction annotates a stream read failure with execution policy. The wrapped error remains available through errors.Is and errors.As.

Types

type AttemptAction added in v1.0.2

type AttemptAction uint8

AttemptAction tells the executor how an attempt failure affects the current route. The executor still applies the one total attempt budget.

const (
	// AttemptActionDefault applies normal retry and route-fallback policy.
	AttemptActionDefault AttemptAction = iota
	// AttemptActionContinueRoute consumes another attempt on the same route
	// without changing provider-health state or applying retry backoff.
	AttemptActionContinueRoute
	// AttemptActionFallbackRoute moves directly to the next planned route
	// without changing provider-health state or applying retry policy.
	AttemptActionFallbackRoute
	// AttemptActionStop ends execution without changing provider-health state.
	AttemptActionStop
)

type AttemptEvidence

type AttemptEvidence struct {
	Number      int
	Route       routing.Route
	Retry       int
	State       State
	StartedAt   time.Time
	FinishedAt  time.Time
	Duration    time.Duration
	Failure     *failure.Failure
	Transitions []Transition
}

AttemptEvidence records one provider invocation or availability skip.

type AttemptOutcome added in v1.0.3

type AttemptOutcome struct {
	Route      routing.Route
	Credential CredentialEvidence
	Failure    *failure.Failure
}

AttemptOutcome is the safe state-transition evidence from one provider invocation.

type Availability

type Availability interface {
	Acquire(routing.Route) bool
	Release(routing.Route)
	RecordSuccess(routing.Route, time.Duration)
	RecordFailure(routing.Route, *failure.Failure, time.Duration)
}

Availability owns attempt admission and offering outcome transitions.

type ChatAttempt

ChatAttempt makes one non-streaming provider invocation.

type ChatResult

type ChatResult struct {
	Response   inference.ChatResponse
	Route      routing.Route
	Attempts   []AttemptEvidence
	StartedAt  time.Time
	FinishedAt time.Time
}

ChatResult is one canonical completed result with execution evidence.

type Clock

type Clock interface {
	Now() time.Time
	Sleep(context.Context, time.Duration) error
}

Clock supplies deterministic attempt time and waits.

type Config

type Config struct {
	MaxAttempts        int
	MaxRetriesPerRoute int
	MaxElapsed         time.Duration
	RetryBackoff       time.Duration
	BackoffMultiplier  float64
	MaxBackoff         time.Duration
}

Config defines the one total execution budget.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns bounded production defaults. A retry and a fallback consume the same MaxAttempts budget.

type CredentialEvidence added in v1.0.3

type CredentialEvidence struct {
	Owner           CredentialOwner
	MaterialVersion string
	Accepted        bool
}

CredentialEvidence identifies one selected credential version without exposing its values or source reference.

type CredentialOwner added in v1.0.3

type CredentialOwner string

CredentialOwner identifies the request credential plane used for one provider attempt. It contains no tenant identity or credential material.

const (
	// CredentialOwnerOperator identifies deployment-owned inference material.
	CredentialOwnerOperator CredentialOwner = "operator"
	// CredentialOwnerTenant identifies request-scoped tenant BYOK material.
	CredentialOwnerTenant CredentialOwner = "tenant"
)

type EmbeddingAttempt added in v1.0.2

EmbeddingAttempt makes one non-streaming provider invocation.

type EmbeddingResult added in v1.0.2

type EmbeddingResult struct {
	Response   inference.EmbeddingResponse
	Route      routing.Route
	Attempts   []AttemptEvidence
	StartedAt  time.Time
	FinishedAt time.Time
}

EmbeddingResult is one canonical completed embedding result with execution evidence.

type Error

type Error struct {
	Reason   error
	Failure  *failure.Failure
	Attempts []AttemptEvidence
}

Error reports terminal execution evidence and preserves the normalized failure.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Is

func (e *Error) Is(target error) bool

Is preserves the terminal budget reason for errors.Is.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap preserves the canonical failure for errors.As.

type Executor

type Executor struct {
	// contains filtered or unexported fields
}

Executor applies one total attempt and elapsed-time budget to one route plan.

func New

func New(
	config Config,
	clock Clock,
	availability Availability,
	outcomes OutcomePublisher,
) (*Executor, error)

New creates an executor with explicit total-budget policy.

func (*Executor) ExecuteChat

func (e *Executor) ExecuteChat(
	ctx context.Context,
	plan *routing.Plan,
	attempt ChatAttempt,
) (*ChatResult, error)

ExecuteChat executes one immutable plan for a non-streaming request.

func (*Executor) ExecuteEmbedding added in v1.0.2

func (e *Executor) ExecuteEmbedding(
	ctx context.Context,
	plan *routing.Plan,
	attempt EmbeddingAttempt,
) (*EmbeddingResult, error)

ExecuteEmbedding executes one immutable plan for an embedding request.

func (*Executor) StartChatStream

func (e *Executor) StartChatStream(
	ctx context.Context,
	plan *routing.Plan,
	attempt StreamAttempt,
) (ManagedStream, error)

StartChatStream starts an execution-owned stream. It can retry or fall back only before it returns the first canonical event to its caller.

type ManagedStream

type ManagedStream interface {
	Stream
	Attempts() []AttemptEvidence
	Committed() bool
	ModelUsed() string
}

ManagedStream exposes execution evidence without changing the protocol stream contract.

type OutcomePublisher added in v1.0.3

type OutcomePublisher interface {
	PublishOutcome(AttemptOutcome)
}

OutcomePublisher receives completed provider invocation outcomes. It must not block on external I/O.

type State

type State string

State is one state in the logical-attempt state machine.

const (
	// StateQueued identifies an attempt that has not started.
	StateQueued State = "queued"
	// StateRunning identifies an active provider attempt.
	StateRunning State = "running"
	// StateSucceeded identifies a completed provider attempt.
	StateSucceeded State = "succeeded"
	// StateFailed identifies a provider attempt that returned a failure.
	StateFailed State = "failed"
	// StateSkipped identifies a route that availability policy rejected.
	StateSkipped State = "skipped"
	// StateCanceled identifies an attempt stopped by context cancellation.
	StateCanceled State = "canceled"
)

type Stream

type Stream interface {
	Read() (*inference.StreamEvent, error)
	Close() error
}

Stream is a provider-neutral inference event stream.

type StreamAttempt

StreamAttempt starts one provider stream. Read failures should be normalized as *failure.Failure values. Wrap a pre-commit read error with WithAttemptAction when it must continue the same route.

type Transition

type Transition struct {
	From State
	To   State
	At   time.Time
}

Transition is one timestamped attempt state transition.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL