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, state.State) → (state.State, error)

Concrete implementations include:

• ReAct — implements the ReAct feedback loop via Run(ctx, state.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.

• WithVerification — wraps any Pattern and runs quality gates after the inner pattern completes, retrying on failure up to a configurable limit. It depends on loop.TurnSubmitter to inject system turns containing verification reports back into the conversation.

Middleware composition is modelled as nesting: patterns depend on the narrowest loop interface they need (TurnRunner or TurnSubmitter), and callers pass a loop.TurnExecutor (which satisfies both) when wiring them together. For example:

WithVerification(ReAct(inner), submitter)

where ReAct requires a TurnRunner and WithVerification requires a TurnSubmitter. The concrete *loop.Step satisfies both interfaces.

Cognitive patterns are conduit-agnostic and stateless. They receive state.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.

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, ...) session.TurnProcessor
• type Pattern
  • func ReActFactory(step loop.TurnExecutor, prov provider.Provider, tracer trace.Tracer) Pattern
  • func WithVerification(inner Pattern, step loop.TurnSubmitter, opts ...VerificationOption) Pattern
• type ReAct
  • func (r *ReAct) Run(ctx context.Context, st state.State) (state.State, error)
• type VerificationOption
  • func WithMaxRetries(n int) VerificationOption
  • func WithVerifiers(v ...verifier.Verifier) VerificationOption

Functions

func NewTurnProcessor

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

NewTurnProcessor returns a session.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 state.State) (state.State, error)
}

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

func ReActFactory

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

ReActFactory returns a Pattern that runs the ReAct cognitive loop.

func WithVerification

func WithVerification(inner Pattern, step loop.TurnSubmitter, opts ...VerificationOption) Pattern

WithVerification wraps a Pattern and runs verifiers after each completion. If verifiers fail, it injects a system turn with the combined report and retries the inner pattern up to maxRetries times. If any verifier returns an Error status, the error is propagated immediately as a fatal error.

type ReAct

type ReAct struct {
	Step     loop.TurnRunner
	Provider provider.Provider
	// 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) Run

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

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

type VerificationOption

type VerificationOption func(*verifyingPattern)

VerificationOption configures the WithVerification wrapper.

func WithMaxRetries

func WithMaxRetries(n int) VerificationOption

WithMaxRetries sets the maximum number of retries on verification failure. Default is 3.

func WithVerifiers

func WithVerifiers(v ...verifier.Verifier) VerificationOption

WithVerifiers sets the verifiers to run after the inner pattern completes.