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") // 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
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.
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.
func CheckResult ¶ added in v0.139.0
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.