probes

type AutoSummarizeOpts ¶

type AutoSummarizeOpts struct {
	Threshold int
	BatchSize int
}

AutoSummarizeOpts configures probed auto-summarization.

type Bound ¶

type Bound struct {
	Min int
	Max int
}

Bound describes the acceptable count range for an operation per Send. A Max of -1 means unbounded.

func AtLeast(n int) Bound

func AtMost(n int) Bound

func Exactly(n int) Bound

func Range(lo, hi int) Bound

func (b Bound) Contains(n int) bool

func (b Bound) String() string

type Op ¶

type Op string

Op is the name of a counted operation, e.g. "store.Load" or "events.template.rendered".

type Ops ¶

type Ops map[Op]Bound

Ops maps an operation name to its expected per-Send bound.

type PipelineInvariants ¶

type PipelineInvariants struct {
	// Label is a free-form name used in failure messages.
	Label string
	// PerSend lists pipeline-wide operations whose count is Send-scoped.
	PerSend Ops
}

PipelineInvariants declares per-Send budgets that hold across the entire pipeline (cross-stage), not for any single stage.

func (p PipelineInvariants) AssertHolds(t *testing.T, snap Snapshot)

type Probes ¶

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

Probes captures observed operation counts for a single Send window.

Probes is wired into the SDK via Run: store calls are counted via a wrapping statestore.Store; events are counted via a SubscribeAll listener on the bus. Renderer / tool / provider counts are derived from existing event types rather than wrapping each interface — the lifecycle events on the bus are already authoritative for "this operation happened once."

For tests that need to inspect event payloads (e.g. assert tokens entering the provider stay within budget), the full event records are retained and exposed via Events(eventType).

A separately-counted Provider wrapper is exposed via SummarizerProvider for auto-summarize tests, since the LLMSummarizer calls Predict on its provider directly without going through the pipeline's ProviderStage (so no provider.call.* events fire for summarization).

Counters are reset by ResetCounters; Run calls it after sdk.Open completes so that init-time Loads/Saves do not appear in Send-scoped snapshots.

func Run(tb testing.TB, ro RunOptions) (*Probes, *sdk.Conversation)

func (p *Probes) Bus() *events.EventBus

func (p *Probes) Events(et events.EventType) []*events.Event

func (p *Probes) ResetCounters()

func (p *Probes) Snapshot() Snapshot

func (p *Probes) SummarizerProvider() providers.Provider

func (p *Probes) WaitForCount(op Op, atLeast int, timeout time.Duration) bool

type RunOptions ¶

type RunOptions struct {
	// PackJSON is the pack definition. If empty, a minimal default is used.
	PackJSON string
	// PromptName selects the prompt within the pack. Defaults to "chat".
	PromptName string
	// ConversationID is passed to sdk.WithConversationID. Defaults to
	// "probes-conv".
	ConversationID string
	// SeedHistory pre-populates the conversation with N prior messages
	// (alternating user/assistant). Used to exercise stages whose work
	// scales with conversation length.
	SeedHistory int
	// SDKOptions are appended after the probe-default options. Caller-supplied
	// options can override defaults (for example, providing a non-mock
	// provider or a different state store), but doing so will defeat the
	// corresponding probe.
	SDKOptions []sdk.Option
	// AutoSummarize, when non-nil, wires sdk.WithAutoSummarize using the
	// probes' counted summarizer provider, so summarizer.Predict shows up
	// in Snapshot.Count.
	AutoSummarize *AutoSummarizeOpts
}

RunOptions configures a probed conversation.

Zero values give a sensible default: a fresh in-memory store, the minimal pack, the "chat" prompt, a deterministic conversation ID, and a mock provider. Tests override only what they need.

type Snapshot ¶

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

Snapshot is an immutable point-in-time view of probe counters.

Operation names follow the convention "<dependency>.<method>" for direct wraps (e.g. "store.Load") and "events.<event_type>" for events (e.g. "events.prompt.template.rendered").

func (s Snapshot) All() map[Op]int

func (s Snapshot) Count(op Op) int

type StageContract ¶

type StageContract struct {
	// Stage is a free-form label used in failure messages.
	Stage string
	// PerSend lists operations whose count is expected to be Send-scoped.
	PerSend Ops
}

StageContract declares the per-Send operation budget for a single stage. Used by tests as a first-class fixture: assert that a stage performs each declared operation within bounds across a matrix of inputs.

func (c StageContract) AssertHolds(t *testing.T, snap Snapshot)