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 ¶
var ( // ErrInvalidRequest indicates a request that fails validation. Kit // returns it before it sends anything. ErrInvalidRequest = errors.New("invalid decision request") // 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 ¶
This section is empty.
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.
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.
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.