Documentation
¶
Overview ¶
Package loopguard is a pure repetition and budget guard for agent action loops: it stops a run that repeats the same action, cycles through a short sequence of actions, or exceeds a cost or action budget, and warns once before a budget runs out. It has no I/O and no clock; the caller persists the snapshot it returns.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type LoopAction ¶
type LoopAction struct {
Tool string `json:"tool"`
ArgsKey string `json:"argsKey"`
CostUsd *float64 `json:"costUsd,omitempty"`
}
LoopAction is one observed tool invocation. CostUsd is optional.
type LoopGuard ¶
type LoopGuard interface {
Observe(action LoopAction) LoopVerdict
// ObserveCost charges provider calls that have no tool action. It does
// not alter repetition or action counts.
ObserveCost(costUsd *float64) LoopVerdict
Snapshot() LoopGuardSnapshot
// Restore ignores a nil snapshot and one with an unknown version.
Restore(snapshot *LoopGuardSnapshot)
}
LoopGuard observes actions and costs and reports when the loop should stop.
func CreateLoopGuard ¶
func CreateLoopGuard(options LoopGuardOptions) LoopGuard
CreateLoopGuard creates a stateful but otherwise pure loop guard.
type LoopGuardOptions ¶
type LoopGuardOptions struct {
// RepeatCap is the number of identical consecutive actions that terminates the loop.
RepeatCap *float64 `json:"repeatCap,omitempty"`
// MaxCyclePeriod is the largest cycle period to inspect.
MaxCyclePeriod *float64 `json:"maxCyclePeriod,omitempty"`
// CycleMinOccurrences is the number of repeated copies required to identify a cycle.
CycleMinOccurrences *float64 `json:"cycleMinOccurrences,omitempty"`
// MaxCostUsd is an optional cumulative USD budget.
MaxCostUsd *float64 `json:"maxCostUsd,omitempty"`
// MaxActions is an optional maximum number of observed actions.
MaxActions *float64 `json:"maxActions,omitempty"`
// WarnFraction is the fraction of a budget at which a one-shot warning is emitted.
WarnFraction *float64 `json:"warnFraction,omitempty"`
}
LoopGuardOptions configures a guard. A nil field selects the default.
type LoopGuardSnapshot ¶
type LoopGuardSnapshot struct {
Version int `json:"version"`
Actions []string `json:"actions"`
ActionCount int `json:"actionCount"`
CumulativeCostUsd float64 `json:"cumulativeCostUsd"`
WarnedCost bool `json:"warnedCost"`
WarnedActions bool `json:"warnedActions"`
Stopped bool `json:"stopped"`
}
LoopGuardSnapshot is the guard's persistable state.
type LoopStatus ¶
type LoopStatus string
LoopStatus is the verdict severity.
const ( LoopStatusOK LoopStatus = "ok" LoopStatusWarn LoopStatus = "warn" LoopStatusStop LoopStatus = "stop" )
type LoopVerdict ¶
type LoopVerdict struct {
Status LoopStatus `json:"status"`
Reason *string `json:"reason,omitempty"`
}
LoopVerdict is the result of observing one action. Reason is nil for an "ok" verdict.
Source Files