config

Documentation

Overview

Package config is the functional-options surface for assembling a pipeline.

Its real job is to make the load-bearing stage ordering from the spec impossible to get wrong. Callers declare *what* they want enabled; this package decides the order:

preprocess → toolcache → rag → dedupe → compress → history → custom → cache-align

RAG must precede compress, and both must precede cache alignment, because a cache breakpoint placed after per-turn content poisons the provider-side cache (spec §2.4.3, §2.4.6). History trimming sits between them: it needs the final payload size to decide what to drop, and alignment needs the final layout to place breakpoints. Routing is not a stage at all — it runs last, after the prompt has its shape, so it can see the real size.

Index

• type Config
  • func New(opts ...Option) Config
  • func (c Config) Stages() []pipeline.Stage
• type Option
  • func WithCacheAlignment(specs ...cache.BreakpointSpec) Option
  • func WithChunkDedupe(opts ...compress.DedupeOption) Option
  • func WithCompression(compressors ...compress.Compressor) Option
  • func WithDefaultCompression() Option
  • func WithHistoryBudget(policy budget.Policy, counter budget.TokenCounter, opts ...history.Option) Option
  • func WithMetrics(r metrics.Recorder) Option
  • func WithPreprocess(rules ...preprocess.Rule) Option
  • func WithRAG(embedder stores.Embedder, store stores.VectorStore, topK int) Option
  • func WithRouter(r pipeline.Router) Option
  • func WithStage(stages ...pipeline.Stage) Option
  • func WithToolCache(store toolcache.Cache, exec toolcache.Executor, ttl time.Duration) Option

Types

type Config

type Config struct {
	Metrics metrics.Recorder

	PreprocessRules []preprocess.Rule

	ToolCache    toolcache.Cache
	ToolExecutor toolcache.Executor
	ToolTTL      time.Duration

	Embedder stores.Embedder
	Store    stores.VectorStore
	TopK     int

	Compressors []compress.Compressor

	// Chunk deduplication. Enabled by WithChunkDedupe.
	DedupeEnabled bool
	DedupeOpts    []compress.DedupeOption

	// History budget enforcement. Enabled only when HistoryPolicy has a
	// non-zero budget for at least one turn type.
	HistoryPolicy  budget.Policy
	HistoryCounter budget.TokenCounter
	HistoryOpts    []history.Option

	AlignerSpecs []cache.BreakpointSpec
	AlignEnabled bool

	ExtraStages []pipeline.Stage

	Router pipeline.Router
}

Config is the resolved set of enabled optimizations. Build it with Options rather than by hand; the zero value is a valid pass-through pipeline.

func New

func New(opts ...Option) Config

New resolves opts into a Config.

func (Config) Stages

func (c Config) Stages() []pipeline.Stage

Stages materializes the enabled optimizations in their required order.

Do not reorder this function's body without re-reading spec §2.4.3 and §2.4.6. The sequence is a correctness constraint, not a preference.

type Option

type Option func(*Config)

Option configures a Config.

func WithCacheAlignment

func WithCacheAlignment(specs ...cache.BreakpointSpec) Option

WithCacheAlignment enables prompt-cache breakpoint placement. Passing no specs uses cache.DefaultSpecs.

func WithChunkDedupe

func WithChunkDedupe(opts ...compress.DedupeOption) Option

WithChunkDedupe drops retrieved chunks that duplicate one already kept.

Retrieval routinely returns the same passage more than once — a README quoted in a wiki, a doc comment mirrored in generated docs — and every copy costs full price while telling the model nothing new.

It runs BEFORE compression: comparing raw text is more reliable than comparing text two compressors have already rewritten, and it means compression is never spent on a chunk that is about to be discarded.

Similarity is lexical (shingled Jaccard), so it catches copies and near copies, not paraphrases. See package compress for the trade-off.

func WithCompression

func WithCompression(compressors ...compress.Compressor) Option

WithCompression compresses retrieved chunks. Compressors are tried in order; the first whose CanHandle returns true wins.

func WithDefaultCompression

func WithDefaultCompression() Option

WithDefaultCompression enables the v1 compressors: JSON first (it is the stricter detector), then conservative prose whitespace collapsing.

func WithHistoryBudget

func WithHistoryBudget(policy budget.Policy, counter budget.TokenCounter, opts ...history.Option) Option

WithHistoryBudget trims the conversation to fit policy before the prompt is assembled, closing the loop budget.Policy previously left open: it computed a budget that nothing enforced.

counter may be nil, in which case budget.CharEstimator is used — free, never fails, and approximate. Pass a provider-backed counter (see anthropic.NewTokenCounter) when trimming against a hard context limit rather than for cost.

The static prefix and the newest message are never touched; see package history for why, and what that costs.

func WithMetrics

func WithMetrics(r metrics.Recorder) Option

WithMetrics attaches one recorder to every stage that reports counters.

func WithPreprocess

func WithPreprocess(rules ...preprocess.Rule) Option

WithPreprocess enables deterministic short-circuiting. Rules are tried in the order given; the first that can handle the request wins.

func WithRAG

func WithRAG(embedder stores.Embedder, store stores.VectorStore, topK int) Option

WithRAG enables retrieval for requests that set NeedsRetrieval.

func WithRouter

func WithRouter(r pipeline.Router) Option

WithRouter selects the model client per request, after every stage has run.

func WithStage

func WithStage(stages ...pipeline.Stage) Option

WithStage appends a caller-supplied stage. It runs after every built-in stage, so it can never displace the ordering the built-ins depend on — in particular it cannot land between RAG and cache alignment.

A stage that must run earlier should be composed by hand with pipeline.New instead of through this package.

func WithToolCache

func WithToolCache(store toolcache.Cache, exec toolcache.Executor, ttl time.Duration) Option

WithToolCache resolves Request.ToolCalls through cache, executing only the misses via exec. A zero ttl caches without expiry.