cognitive

Documentation

Overview

Package cognitive defines cognitive patterns that drive multi-turn inference loops. A cognitive pattern decides when to stop looping based on the state of the conversation — for example, ReAct loops while tool results are pending, and stops when the assistant produces a final response.

The core abstraction is the Pattern interface:

• Pattern — Run(ctx, ledger.State) → (ledger.State, error)

Concrete implementations include:

• ReAct — implements the ReAct feedback loop via Run(ctx, ledger.State). It depends on loop.TurnRunner (not the concrete *loop.Step) so it can be composed with any component that can run a single inference turn.

Cognitive patterns are conduit-agnostic and stateless. They receive ledger.State as a parameter and return it, without embedding it. The caller (typically application-level code) is responsible for IO wiring: reading conduit events, appending user messages, routing output events to a conduit, and managing status.

Verification wrappers — Pattern implementations that run quality gates after the inner pattern completes and inject a retry turn on failure — live in the x/verifier package, alongside the concrete Verifier primitives they compose. See verifier.WithVerification.

See also: loop package — the single-turn execution primitive, EventBus / Pipeline decomposition, and the TurnRunner / TurnSubmitter / TurnExecutor interfaces.

Index

• func NewTurnProcessor(factory func(loop.TurnExecutor, provider.Provider, trace.Tracer) Pattern, ...) junk.TurnProcessor
• type Pattern
  • func ReActFactory(step loop.TurnExecutor, prov provider.Provider, tracer trace.Tracer) Pattern
• type ReAct
  • func (r *ReAct) Name() string
  • func (r *ReAct) Run(ctx context.Context, st ledger.State) (ledger.State, error)
  • func (r *ReAct) SetRuntime(step loop.TurnRunner, provider provider.Provider, spec models.Spec, ...)
• type SingleShot
  • func (s *SingleShot) Name() string
  • func (s *SingleShot) Run(ctx context.Context, st ledger.State) (ledger.State, error)
  • func (s *SingleShot) SetRuntime(step loop.TurnRunner, provider provider.Provider, spec models.Spec, ...)

Functions

func NewTurnProcessor

func NewTurnProcessor(factory func(loop.TurnExecutor, provider.Provider, trace.Tracer) Pattern, tracer trace.Tracer) junk.TurnProcessor

NewTurnProcessor returns a junk.TurnProcessor that runs the given Pattern factory for each turn. The factory receives the session's loop.Step and provider so it can construct stateful Patterns like ReAct.

Types

type Pattern

type Pattern interface {
	Run(ctx context.Context, st ledger.State) (ledger.State, error)
	Name() string
}

Pattern is a cognitive pattern that can run a multi-turn inference loop starting from a given ledger. Implementations decide when to stop based on the conversation state (e.g., when no pending tool calls remain).

Name returns a stable, lowercase identifier for the pattern (e.g. "react", "single_shot", "verified") used by the agent bundle for tracing and observability. It is part of the Pattern contract: any new pattern must implement it.

func ReActFactory

func ReActFactory(step loop.TurnExecutor, prov provider.Provider, tracer trace.Tracer) Pattern

ReActFactory returns a Pattern that runs the ReAct cognitive loop.

type ReAct

type ReAct struct {
	Step     loop.TurnRunner
	Provider provider.Provider
	Spec     models.Spec
	// contains filtered or unexported fields
}

ReAct is a cognitive pattern that implements the ReAct feedback loop: it repeatedly invokes Step.Turn() while the last turn in state is not from the assistant (indicating pending tool results), driving the assistant to reason, act, and observe until no more tool calls remain.

func (*ReAct) Name

func (r *ReAct) Name() string

Name returns the pattern identifier, used by the agent bundle for tracing the agent.run span. Stable across versions.

func (*ReAct) Run

func (r *ReAct) Run(ctx context.Context, st ledger.State) (ledger.State, error)

Run executes the ReAct feedback loop starting from the given ledger. It returns when the last turn is from the assistant (no pending tool calls) or when the context is cancelled.

func (*ReAct) SetRuntime

func (r *ReAct) SetRuntime(step loop.TurnRunner, provider provider.Provider, spec models.Spec, tracer trace.Tracer)

SetRuntime is implemented by patterns that want the agent bundle to inject its runtime dependencies at construction. The agent's New type-asserts to this anonymous interface and calls it after building the step. Patterns that do not implement SetRuntime cannot be used with the agent bundle (their Step/Provider/Spec fields would remain nil).

type SingleShot

type SingleShot struct {
	Step     loop.TurnRunner
	Provider provider.Provider
	Spec     models.Spec
}

SingleShot is a cognitive pattern that runs exactly one inference turn and returns. It is the strategy for callers that want "ask the model once and act on the response" — compaction, judging, auto-titling, code review, test generation.

The pattern has no loop and no terminal-detection: it is a zero-state one-step over the underlying loop.TurnRunner. Callers compose the SingleShot agent with WithTransforms/WithHandlers in the agent bundle to apply the same configuration (compaction transform, system prompt, telemetry handler) as the main conversation.

func (*SingleShot) Name

func (s *SingleShot) Name() string

Name returns the pattern identifier, used by the agent bundle for tracing the agent.run span. Stable across versions.

func (*SingleShot) Run

func (s *SingleShot) Run(ctx context.Context, st ledger.State) (ledger.State, error)

Run invokes the underlying step exactly once and returns the resulting ledger. The pattern does no terminal-detection; the caller's agent configuration (transforms, handlers) determines what happens to the produced turn.

func (*SingleShot) SetRuntime

func (s *SingleShot) SetRuntime(step loop.TurnRunner, provider provider.Provider, spec models.Spec, _ trace.Tracer)

SetRuntime is implemented by patterns that want the agent bundle to inject its runtime dependencies at construction. The agent's New type-asserts to this anonymous interface and calls it after building the step. Patterns that do not implement SetRuntime cannot be used with the agent bundle (their Step/Provider/Spec fields would remain nil).

tracer is accepted for interface uniformity but is unused by SingleShot (the pattern emits no spans of its own; the agent's agent.run span is the only one).