pipeline

type Decider struct {
	Router *models.Router // nil = no decision model is set
	// Override returns the router for a rule's own model, or nil when it cannot be used.
	Override      func(ctx context.Context, spec string) *models.Router
	MinConfidence float64   // act threshold for rules that set none
	Now           time.Time // for age_days
	// Examples returns the user's corrections to show the fallback model for this email,
	// most similar first; candidates are the rule ids on offer. nil = show none.
	Examples func(ctx context.Context, email message.Summary, candidates []int64) []learn.Example
	// Own are the mailbox's own addresses, whose mail is left alone: no sender rule, rule or
	// model is consulted for it. Empty = none (the leave_own_mail setting is off). See OwnMail.
	Own []string
	// RouteOnly are rules a sender rule may route to although they are not in the rules
	// given to Settle (see rules.Options.RouteOnly). nil = none.
	RouteOnly []rules.Rule
	// Allowance, when set, says whether the tenant's monthly allowance of emails a model
	// decides on keys the operator holds is used up. While it is, no model on those keys is
	// asked: a model on the tenant's own keys decides (models.Router.OwnKeysOnly), or else
	// the email waits in Needs review (ReasonAllowance). Sender rules and rules without an
	// intent decide as ever. nil = no allowance (self-host).
	Allowance func(ctx context.Context) (reached bool, err error)
	// Spend, when set, counts each email a model decides on keys the operator holds as Settle
	// decides it: a cleanup check's, which records no decision. Live sorting leaves it nil and
	// counts with the decision's row (store.Decision.Metered).
	Spend func(ctx context.Context) error
}

type Executor interface {
	Apply(ctx context.Context, d actions.DecisionRecord, acts []rules.Action, batchID int64) ([]actions.ActionRecord, error)
	ApplyMany(ctx context.Context, ms []actions.Many, a rules.Action, batchID int64) (dry bool, errs []error)
}

type Outcome struct {
	rules.Result
	RuleName string // the name of Result.RuleID; empty when there is none
	Reason   string // one sentence saying why
	Asked    bool   // a model was asked
	// NoModel: rules with an intent were in play and no model could be asked, so they were
	// passed over. With a model set, this is an email the model would have decided.
	NoModel bool
	// Metered: a model on keys the operator holds decided the email, so it counts against the
	// tenant's monthly allowance.
	Metered bool
	Calls   int          // how many model calls that took, counting retries and the fallback
	Usage   models.Usage // what asking cost, over every call made
	// Probabilities is what the decision model gave each candidate, by rule id (0 = none
	// of them); nil when it gives none.
	Probabilities map[int64]float64
}

type Pipeline struct {
	Store   *store.Store
	Mailbox mail.Mailbox
	Account store.Account
	Router  *models.Router // nil = no decision model is set
	Exec    Executor       // nil = record decisions only
	Hub     *events.Hub    // nil = publish nothing

	MinConfidence float64 // act threshold for rules that set none
	BodyChars     int     // plain-text characters shown to models
	// Live, when set, supplies Router and MinConfidence afresh for every message from the
	// settings of the account's tenant, so a change made in Settings needs no restart
	// (settings.Settings.Live).
	Live func(ctx context.Context, tenantID int64) (router *models.Router, minConfidence float64)
	// Override returns the tenant's router for a rule's own model (rules.Rule.Model), or nil
	// when that model cannot be used (settings.Settings.RouterFor). nil = rules' models are ignored.
	Override func(ctx context.Context, tenantID int64, spec string) *models.Router

	// Batch is the batch the actions belong to. 0 = the day's live batch; a cleanup run
	// sets its own, so the whole run can be undone as one.
	Batch int64
	// Spent, when set, is told what each model decision cost: a cleanup run shows the total.
	Spent func(tokens int, costUSD float64)
	// Allowance, when set, says whether a tenant's monthly allowance of emails a model
	// decides on keys the operator holds is used up at now (Decider.Allowance). An email
	// counted already (a message tried again) is decided as before. nil = no allowance.
	Allowance func(ctx context.Context, tenantID int64, now time.Time) (reached bool, err error)
	// Halted, when set, says whether the tenant's mail must not be sorted at now: its plan
	// ended (a build that sells plans, ext.Module.Billing). While it is, Process, Sort,
	// SortSaved and RetryDue leave every message as it is, the folder's watch position
	// included, and answer ErrHalted; the supervisor then stops. Mail that arrived meanwhile
	// is sorted when the mailbox starts again with a plan, as after a pause: the watcher
	// resumes from the stored position. nil = never halted.
	Halted func(ctx context.Context, tenantID int64, now time.Time) (bool, error)

	Now func() time.Time // nil = time.Now
	// Rediscover re-runs folder discovery. It is called once when a step fails because a
	// folder is unknown, and the step is then tried again. nil = never.
	Rediscover func(ctx context.Context) error
}

type Saved struct {
	Ref mail.MsgRef
	Out Outcome
}