pattern

Documentation

Overview

Package pattern composes System One answers into the shapes the TypeSafe docs describe: confidence-gated routing, composite scoring, and walking a taxonomy one Choice at a time.

Everything here is ordinary code over answers the systemone package returns. The thresholds and weights are yours to set and to evaluate against your own data; nothing in this package decides policy for you.

See https://docs.typesafe.ai/patterns.

Index

• func Composite(terms ...Term) float64
• type Band
  • func (b Band) String() string
• type Step
  • func Walk(ctx context.Context, c *systemone.Client, state any, tree Tree, ...) ([]Step, error)
• type Term
  • func Weigh[T ~int](a systemone.ScoreAnswer[T], weight float64) Term
  • func WeighNoul(a systemone.NoulAnswer, weight float64) Term
• type Thresholds
  • func (t Thresholds) Band(confidence float64) Band
• type Tree
• type WalkOption
  • func WithInstructions(f func(path []string) systemone.Content) WalkOption
  • func WithMaxDepth(n int) WalkOption
  • func WithMinConfidence(min float64) WalkOption
  • func WithQuestionID(id string) WalkOption
  • func WithSubtreeDepth(n int) WalkOption

Functions

func Composite

func Composite(terms ...Term) float64

Composite is the weighted mean of the terms, or 0 when the weights sum to zero. Weights live in code, so changing one reranks existing answers without a new request.

A weighted mean lets a strong dimension compensate for a weak one. When a single dimension must be disqualifying on its own, test it separately instead of folding it into the mean.

Types

type Band

type Band int

Band is a coarse reading of an answer's confidence, used to pick how much autonomy to give a decision. See https://docs.typesafe.ai/confidence.

const (
	// Low means do not act: route to a person, ask for clarification, or fall
	// back to another system.
	Low Band = iota
	// Medium means proceed with care: confirm, flag for review, or gather more
	// evidence first.
	Medium
	// High means act automatically.
	High
)

func (Band) String

func (b Band) String() string

type Step

type Step struct {
	// Name is the category chosen at this level.
	Name string
	// Confidence is the Choice answer's confidence at this level.
	Confidence float64
	// Probabilities are every sibling's probability at this level. Use them to
	// keep more than one branch alive when the top two are close.
	Probabilities map[string]float64
}

Step is one level of a classification walk.

func Walk

func Walk(ctx context.Context, c *systemone.Client, state any, tree Tree, opts ...WalkOption) ([]Step, error)

Walk classifies state down a taxonomy, asking one Choice per level with the current node's children as the options and each child's subtree as its description. Showing the subtree lets the model see what lives under a branch before committing to it.

The walk is greedy: it follows the highest-probability child at each level. Every step carries the full sibling distribution, so a caller that wants a beam search can run Walk's per-level question itself and keep several paths.

It stops at a leaf, at MaxDepth, or at the first step below MinConfidence, returning the steps taken so far.

See https://docs.typesafe.ai/cookbooks/hierarchical_classification.

type Term

type Term struct {
	Value  float64
	Weight float64
}

Term is one weighted dimension of a composite score. Value is expected on a 0 to 1 scale so dimensions with different level counts combine fairly.

func Weigh

func Weigh[T ~int](a systemone.ScoreAnswer[T], weight float64) Term

Weigh turns a Score answer into a Term, normalizing it to 0 to 1.

func WeighNoul

func WeighNoul(a systemone.NoulAnswer, weight float64) Term

WeighNoul turns a Noul answer into a Term. The probability of yes is already on a 0 to 1 scale.

type Thresholds

type Thresholds struct {
	Medium float64
	High   float64
}

Thresholds splits confidence into three bands. Both boundaries are inclusive lower bounds, so confidence exactly equal to High reads as High.

Set them per action rather than per system: showing the wrong screen and approving a transfer deserve different bars.

func (Thresholds) Band

func (t Thresholds) Band(confidence float64) Band

Band places a confidence value.

type Tree

type Tree map[string]Tree

Tree is a taxonomy. Each key is a category name and its value holds that category's children; a nil or empty value is a leaf.

type WalkOption

type WalkOption func(*walk)

WalkOption configures Walk.

func WithInstructions

func WithInstructions(f func(path []string) systemone.Content) WalkOption

WithInstructions replaces the per-level question text. The argument is the path chosen so far, empty at the top level.

func WithMaxDepth

func WithMaxDepth(n int) WalkOption

WithMaxDepth stops the walk after n levels. Zero, the default, walks to a leaf.

func WithMinConfidence

func WithMinConfidence(min float64) WalkOption

WithMinConfidence stops the walk before the first step whose confidence falls below min, leaving the classification at the last level it was sure of.

func WithQuestionID

func WithQuestionID(id string) WalkOption

WithQuestionID sets the question ID used at each level. It never reaches the model.

func WithSubtreeDepth

func WithSubtreeDepth(n int) WalkOption

WithSubtreeDepth limits how many levels of each option's subtree are shown to the model. Deep subtrees cost tokens and crowd the question; the default shows two levels. Zero shows the option names alone.