Documentation
¶
Overview ¶
Package reminder defines core types for run-scoped system reminders used to provide backstage guidance to planners (safety, correctness, workflow, and context hints). The package is intentionally small and policy-agnostic; the runtime owns evaluation and injection semantics.
Index ¶
Constants ¶
const DefaultExplanation = `` /* 399-byte string literal not displayed */
DefaultExplanation is a generic explanation of system reminders suitable for inclusion in agent system prompts. It documents <system-reminder> blocks as platform-added guidance that should not be surfaced verbatim to end users.
Variables ¶
This section is empty.
Functions ¶
func InjectMessages ¶
InjectMessages returns a copy of messages with the provided reminders injected as additional system messages at appropriate attachment points.
The helper follows a conservative strategy:
- AttachmentRunStart reminders are grouped into a single system message prepended to the transcript (or merged into the first existing system message when present).
- All other reminders are grouped into a single system message inserted immediately before the last user message. When no user message exists, they are appended as a trailing system message.
Reminders are expected to be pre-ordered by priority (e.g., via Engine); InjectMessages preserves the relative order it receives.
Types ¶
type Attachment ¶
type Attachment struct {
// Kind identifies the conceptual attachment location (run start, user
// turn).
Kind AttachmentKind
// Tool identifies the fully qualified tool name. It is reserved for
// future use and left empty by current callers.
Tool tools.Ident
}
Attachment scopes a reminder to a particular attachment point in the conversation.
type AttachmentKind ¶
type AttachmentKind string
AttachmentKind describes where a reminder should conceptually attach in the conversation. The current implementation distinguishes only between run start and per-turn attachments.
const ( // AttachmentRunStart reminders attach to the start of a run, alongside // session context and user preferences. AttachmentRunStart AttachmentKind = "run_start" // AttachmentUserTurn reminders attach to user turns, shaping how the // planner interprets the next user message. AttachmentUserTurn AttachmentKind = "user_turn" )
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine manages run-scoped reminders. It tracks per-run reminder state and enforces simple lifetime policies (per-run caps and turn-based rate limiting). Engines are safe for concurrent use.
The Engine does not itself perform prompt injection; callers obtain the per-turn snapshot via Snapshot and pass reminders to planners or prompt builders as needed.
func NewEngine ¶
func NewEngine() *Engine
NewEngine constructs an Engine. Callers add reminders directly via AddReminder and obtain snapshots via Snapshot.
func (*Engine) AddReminder ¶
AddReminder registers or updates a reminder for the given run. When a reminder with the same ID already exists, its configuration is replaced while preserving emission counters so rate limiting continues to apply.
Empty run IDs or reminder IDs are ignored.
func (*Engine) RemoveReminder ¶
RemoveReminder removes a reminder with the given ID from a run. It is a no-op when the run or reminder is unknown.
func (*Engine) Snapshot ¶
Snapshot returns the reminders that should be emitted for the next planner turn of the given run. It enforces per-run caps and turn-based rate limits, updates internal counters, and returns reminders ordered by priority tier (safety first) and ID for stability.
When the run is unknown or has no active reminders, Snapshot returns nil.
type Reminder ¶
type Reminder struct {
// ID is the stable identifier for this reminder type within a run. It is
// used for de-duplication, rate limiting, and telemetry. IDs should be
// deterministic (e.g., "pending_todos", "partial_result.ad.search").
ID string
// Text is the natural-language guidance to inject, typically wrapped in a
// domain-specific tag such as <system-reminder>...</system-reminder>.
Text string
// Priority controls ordering and suppression. Lower tiers (TierSafety)
// always take precedence over higher tiers.
Priority Tier
// Attachment indicates where in the conversation this reminder should be
// associated (run start or user turn).
Attachment Attachment
// MaxPerRun caps how many times this reminder may be emitted in a single
// run. Zero means unlimited. TierSafety reminders should generally leave
// this unset to avoid ever being dropped, though the Engine still
// de-duplicates repeated emissions per turn.
MaxPerRun int
// MinTurnsBetween enforces a minimum number of planner turns between
// emissions. Zero means no rate limit. This is typically used for
// TierCorrect/TierGuidance reminders to avoid noisy repetition.
MinTurnsBetween int
}
Reminder describes concrete guidance that should be injected into prompts. Reminders are produced by application code and evaluated by the Engine on a per-run basis to enforce lifetime and rate limiting.
type Tier ¶
type Tier int
Tier represents the priority tier for a reminder. Lower-valued tiers carry higher precedence when enforcing caps or resolving conflicts.
const ( // TierSafety is the highest priority tier (P0). Safety reminders must // never be dropped by policy; they may be de-duplicated but not // suppressed due to lower-priority budgets. TierSafety Tier = iota // TierGuidance carries workflow suggestions and soft nudges (P2). These // are lowest priority and are the first to be suppressed when prompt // budgets are tight. TierGuidance )
Source Files