Files
archipelago/sdk/guard/guard.go
T

154 lines
4.1 KiB
Go

// Package guard is what a Go guard extension builds on: the generated
// guard.v1 contract, the interface a guard implements and the Serve helper
// archie-core launches it with.
package guard
import (
"context"
"encoding/json/jsontext"
"time"
)
// Contract is the guard contract version this SDK speaks.
const Contract = "v1"
// Ceiling is the five-level scale a guard answers with, from the most
// autonomy to the least. The action runs at the lowest ceiling any guard sets.
type Ceiling int
// The five levels. The zero Ceiling means the guard gave none, which holds the
// action at propose and wait.
const (
ActQuietly Ceiling = iota + 1
ActAndTell
ProposeAndWait
Escalate
Never
)
// Strength is how much a finding's evidence supports it.
type Strength int
// Evidence strengths.
const (
StrengthUnspecified Strength = iota
Weak
Moderate
Strong
)
// Config is the operator's settings and the host-resolved secrets.
type Config struct {
Settings map[string]string
Secrets map[string]string
}
// Description names the guard and says whether its verdicts count.
type Description struct {
Name string
Version string
// Advisory verdicts are recorded and set no ceiling.
Advisory bool
}
// Action is one concrete action put to the guard.
type Action struct {
Connector string
Name string
Input jsontext.Value
Digest string
Target Target
Effect Effect
RunID string
// DecisionKey identifies the attempt to run the action.
DecisionKey string
// Deadline is how long the host waits for the verdict.
Deadline time.Duration
// At is the host's clock when the action was put to the guard.
At time.Time
// Diagnosis is what the proposing agent concluded so far, in its own
// words. Empty when no agent proposed the action.
Diagnosis string
// Evidence is what the agent read during the run, oldest first.
Evidence []Evidence
}
// Evidence is one result the agent read, as the tool returned it.
type Evidence struct {
Source string
Text string
}
// Target is what the action acts on.
type Target struct {
Kind string
ID string
Environment string
Disposable bool
}
// Effect is what the connector says the action does.
type Effect struct {
ReadOnly bool
// Reversibility is 1 (undone automatically), 2 (recoverable), 3
// (irreversible), or 0 when the connector declared none.
Reversibility int
Summary string
}
// Finding is one thing the guard noticed, with what it rests on.
type Finding struct {
Text string
Evidence string
Strength Strength
}
// Verdict is a guard's judgement of one action. A guard with no concern
// returns Ceiling ActQuietly and no findings.
type Verdict struct {
Ceiling Ceiling
Findings []Finding
BlindSpots []string
// Judges is every model judgement the verdict rests on, clean answers
// included, so the verdict can be audited without asking the model again.
Judges []JudgeRecord
}
// JudgeRecord is what one model judge answered and what it was judged on.
type JudgeRecord struct {
Model string
// ResultID identifies the judge's result with the service that ran it.
ResultID string
Answer string
Confidence float64
// Reason is the judge's reasoning, or why the call failed.
Reason string
// Basis is the text the judge was given beyond the action, such as the
// policy rules, and BasisDigest its SHA-256 in hex.
Basis string
BasisDigest string
// Answers is every answer as JSON: choice, probabilities and confidence.
Answers []byte
// Trusted says the judge has passed its recorded eval. When it hasn't,
// AdvisoryReason says why.
Trusted bool
AdvisoryReason string
// EvalDate is the day of the eval the judge's standing comes from.
EvalDate string
// Request and Response are the exact bodies the judge endpoint was sent
// and returned, kept even when the call failed.
Request []byte
Response []byte
EndpointPath string
HTTPStatus int
LatencyMS int64
}
// Guard judges one concrete action.
type Guard interface {
Describe() Description
// Judge returns the verdict. An error holds the action at propose and
// wait, unless the guard is advisory.
Judge(ctx context.Context, a Action) (Verdict, error)
}