decision

package
v0.144.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 21, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package decision sends typed questions to decision models and normalizes their answers. Decision models answer each question with probabilities instead of generated text.

The package speaks three wires (see models.DecisionWire): SystemOne (the TypeSafe request shape that most hosts speak), Cloudflare Workers AI (the SystemOne body in Cloudflare's envelope) and the Vercel AI Gateway decision protocol. Callers use one request and one result shape for all of them.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrInvalidRequest indicates a request that fails validation. Kit
	// returns it before it sends anything.
	ErrInvalidRequest = errors.New("invalid decision request")

	// ErrNoModel indicates that neither the request nor the configuration
	// names a decision model.
	ErrNoModel = errors.New("no decision model")

	// ErrInvalidResponse indicates an answer set that does not match the
	// questions: a missing answer, a wrong type or an unknown option.
	ErrInvalidResponse = errors.New("invalid decision response")

	// ErrRefused indicates that the model refused to answer a question.
	ErrRefused = errors.New("decision model refused the question")

	// ErrNoAnswer indicates that a result has no answer with the given ID.
	ErrNoAnswer = errors.New("no answer for question")

	// ErrWrongAnswerType indicates an accessor for a different question type.
	ErrWrongAnswerType = errors.New("wrong answer type")
)

Errors returned by Decide and the answer accessors.

Functions

func CheckRequest added in v0.139.0

func CheckRequest(req Request) error

CheckRequest validates req for a decision model that runs in process (one that an application supplies). It applies the question rules of every wire, but no wire limits: the model decides how many questions and which image types it accepts. It returns an error that wraps ErrInvalidRequest.

Types

type APIError

type APIError struct {
	StatusCode int
	// Message is the provider's error message, when the body has one.
	Message string
	// Body is the raw response body.
	Body string
}

APIError is an HTTP error from a decision provider.

func (*APIError) Error

func (e *APIError) Error() string

type Answer

type Answer struct {
	ID   string       `json:"id"`
	Type QuestionType `json:"type"`
	// Refused is true when the model refused the question. The other
	// fields are then zero.
	Refused bool `json:"refused,omitempty"`
	// Probability is P(true) for a boolean question.
	Probability float64 `json:"probability,omitempty"`
	// Choice is the selected option of a choice question.
	Choice string `json:"choice,omitempty"`
	// Score is the expected level of a score question, in [0, levels-1].
	// It can be fractional.
	Score float64 `json:"score,omitempty"`
	// Level is the most probable level of a score question.
	Level int `json:"level,omitempty"`
	// Distribution has the probability of each option or level, in
	// question order. Nil when the model returns none.
	Distribution []Probability `json:"distribution,omitempty"`
	// Confidence shows how strongly the distribution favors one answer. It
	// is not the probability that the answer is correct. Nil when the model
	// returns none.
	Confidence *float64 `json:"confidence,omitempty"`
}

Answer is the normalized answer to one question.

func (Answer) Prob

func (a Answer) Prob(name string) (p float64, ok bool)

Prob returns the probability of the named option or level. ok is false when the distribution does not include it.

type Image

type Image struct {
	// MediaType is the image type, for example "image/png".
	MediaType string `json:"media_type"`
	Data      []byte `json:"data"`
	// Filename is optional.
	Filename string `json:"filename,omitempty"`
}

Image is an image attached to the state.

type Option

type Option struct {
	// Name is the value returned when the model selects this option.
	Name string `json:"name"`
	// Description tells the model what the option means. Empty lets the
	// name describe itself.
	Description string `json:"description,omitempty"`
}

Option is one answer of a choice question.

type Probability

type Probability struct {
	// Index is the position of the option or level in the question.
	Index int `json:"index"`
	// Name is the option name or the level text.
	Name        string  `json:"name"`
	Probability float64 `json:"probability"`
}

Probability is the probability of one option or level.

type Question

type Question struct {
	// ID identifies the answer. It must be unique in the request.
	ID   string       `json:"id"`
	Type QuestionType `json:"type"`
	// Instructions state the question.
	Instructions string `json:"instructions,omitempty"`
	// Options are the answers of a choice question, in order.
	Options []Option `json:"options,omitempty"`
	// Levels are the steps of a score question, lowest first.
	Levels []string `json:"levels,omitempty"`
	// True and False optionally describe the two cases of a boolean
	// question.
	True  string `json:"true,omitempty"`
	False string `json:"false,omitempty"`
}

Question is one typed question. Use the fields that match Type.

type QuestionType

type QuestionType string

QuestionType is the kind of a question.

const (
	// Boolean questions are answered with P(true).
	Boolean QuestionType = "boolean"
	// Choice questions are answered with one option from a named set.
	Choice QuestionType = "choice"
	// Score questions are answered with a position on an ordered scale.
	Score QuestionType = "score"
)

type Request

type Request struct {
	State     State      `json:"state"`
	Questions []Question `json:"questions"`
	// ProviderOptions are sent as-is on wires that accept them (Vercel AI
	// Gateway), for example {"gateway": {"zeroDataRetention": true}}.
	ProviderOptions map[string]any `json:"provider_options,omitempty"`
}

Request is one decision request.

type Result

type Result struct {
	// Answers are in question order.
	Answers []Answer `json:"answers"`
	// Model is the model that answered, as reported by the provider (for
	// example a resolved version such as "jev-1.14.0").
	Model string `json:"model,omitempty"`
	Usage Usage  `json:"usage"`
	// Metadata holds provider-specific data, such as gateway routing and
	// cost.
	Metadata map[string]any `json:"metadata,omitempty"`
}

Result is the normalized result of one request.

func CheckResult added in v0.139.0

func CheckResult(req Request, res *Result) (*Result, error)

CheckResult normalizes the result of an in-process decision model in the same way as a wire response. Each question must have exactly one answer of its type, and no answer may have an unknown ID. CheckResult puts the answers in question order, puts the distributions in option or level order and sets Level from the distribution (else from Score). It returns an error that wraps ErrInvalidResponse. res is not changed.

func Decide

func Decide(ctx context.Context, ep *models.DecisionEndpoint, req Request) (*Result, error)

Decide validates req, sends it to ep and returns the normalized result.

func (*Result) Answer

func (r *Result) Answer(id string) (Answer, bool)

Answer returns the answer with the given ID.

func (*Result) Boolean

func (r *Result) Boolean(id string) (Answer, error)

Boolean returns the answer to a boolean question.

func (*Result) Choice

func (r *Result) Choice(id string) (Answer, error)

Choice returns the answer to a choice question.

func (*Result) Score

func (r *Result) Score(id string) (Answer, error)

Score returns the answer to a score question.

type State

type State struct {
	Text string `json:"text,omitempty"`
	// JSON is any value that encodes to JSON: a struct, map or slice.
	JSON   any     `json:"json,omitempty"`
	Images []Image `json:"images,omitempty"`
}

State is what the questions are about. Set Text, JSON or both, and optionally Images.

type Usage

type Usage struct {
	InputTokens  int64 `json:"input_tokens"`
	OutputTokens int64 `json:"output_tokens"`
}

Usage is the token usage of one request.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL