Documentation
¶
Overview ¶
Package registry loads the embedded Jev question-set registry and applies the act/gather/fallback decision policy to answers.
Thresholds come only from the registry: nothing in this package accepts a caller-supplied act or escalate threshold.
Index ¶
Constants ¶
const ( Act = "act" Gather = "gather" Fallback = "fallback" )
Decisions.
const ( ReasonOptionNotOffered = "option-not-offered" ReasonShadow = "shadow" )
Reasons attached to a decision.
Variables ¶
var ErrNoDecision = errors.New("registry: no decision possible")
ErrNoDecision reports answers that cannot be decided: the set declares no usable primary question, the primary answer is missing, or its confidence is not a finite number.
var ErrUnknownSet = errors.New("registry: unknown question set")
ErrUnknownSet reports a question set id that is not registered.
Functions ¶
func AppendDecision ¶
AppendDecision writes dec as one line of <stateDir>/jevkit/decisions.jsonl.
func DecisionsPath ¶
DecisionsPath is <stateDir>/jevkit/decisions.jsonl.
Types ¶
type Decider ¶
type Decider struct {
Registry *Registry
// StateDir holds jevkit/decisions.jsonl. Empty disables logging.
StateDir string
// Getenv reads JEVKIT_SHADOW; nil means os.Getenv.
Getenv func(string) string
// Now stamps records; nil means time.Now.
Now func() time.Time
}
Decider applies a registry's policy and logs each decision.
func (*Decider) Decide ¶
Decide decides answers (question id to answer) against the set id.
The primary question's answer supplies the confidence: choice and score answers carry one, a noul answer's value is its confidence. A choice that is not among a non-empty criteria set is a fallback. With JEVKIT_SHADOW=1 the would-have decision is logged and the returned decision is fallback.
func (*Decider) DecideWith ¶
func (d *Decider) DecideWith(id string, answers map[string]jev.Answer, callTime map[string]map[string]json.RawMessage) (Decision, error)
DecideWith validates primary choices against declared and call-time options.
func (*Decider) DecideWithConfidence ¶
func (d *Decider) DecideWithConfidence(id string, answers map[string]jev.Answer, callTime map[string]map[string]json.RawMessage, confidence float64) (Decision, error)
DecideWithConfidence applies the registered thresholds to a conservative confidence derived from the primary answer's probability distribution. The original answer, including its distribution, is kept in the decision log.
type Decision ¶
type Decision struct {
Timestamp string `json:"timestamp"`
Decision string `json:"decision"`
Chosen *string `json:"chosen"`
Confidence float64 `json:"confidence"`
QuestionSetID string `json:"questionSetId"`
QuestionSetVersion int `json:"questionSetVersion"`
Surface string `json:"surface"`
Reason string `json:"reason"`
Shadow bool `json:"shadow,omitempty"`
FallbackUsed bool `json:"fallbackUsed"`
Answers map[string]interface{} `json:"answers,omitempty"`
RegistryVersion string `json:"registryVersion"`
CommandFamily string `json:"commandFamily,omitempty"`
PolicyRuleID string `json:"policyRuleId,omitempty"`
Runtime string `json:"runtime,omitempty"`
ReviewID string `json:"reviewId,omitempty"`
BytesBefore int `json:"bytesBefore,omitempty"`
BytesAfter int `json:"bytesAfter,omitempty"`
LinesBefore int `json:"linesBefore,omitempty"`
LinesAfter int `json:"linesAfter,omitempty"`
}
Decision is the policy outcome for one set of answers and one decisions.jsonl line.
In shadow mode the value returned to the caller has Decision "fallback", while the logged record keeps the would-have decision.
type Policy ¶
type Policy struct {
PrimaryQuestion string `json:"primaryQuestion"`
ActThreshold float64 `json:"actThreshold"`
EscalateThreshold float64 `json:"escalateThreshold"`
Fallback string `json:"fallback"`
// GatherHint, when set, tells a caller what evidence to add before
// asking again after a gather decision.
GatherHint string `json:"gatherHint,omitempty"`
}
Policy holds a set's decision thresholds.
type Question ¶
type Question struct {
Type string `json:"type"`
Instructions string `json:"instructions"`
Criteria json.RawMessage `json:"criteria,omitempty"`
CriteriaMode string `json:"criteriaMode,omitempty"`
}
Question is one registered question definition.
type Registry ¶
type Registry struct {
RegistryVersion string `json:"registryVersion"`
QuestionSets map[string]*Set `json:"questionSets"`
}
Registry is the parsed question-set registry.
func Parse ¶
Parse validates raw against the embedded schema and the per-type shape rules the schema cannot express, then returns the parsed registry.
type Set ¶
type Set struct {
ID string `json:"id"`
Version int `json:"version"`
Surface string `json:"surface"`
Description string `json:"description"`
Questions map[string]Question `json:"questions"`
Policy Policy `json:"policy"`
Calibration string `json:"calibration,omitempty"`
}
Set is one registered question set.
Source Files