From 3091e4f5579637f2c3c865b2f325a36b97f5579e Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Mon, 16 Nov 2026 11:13:42 +1100 Subject: [PATCH] feat(guards): every model guard attaches a judge record to every verdict, clean answers and failed calls included (archie audit requirement: a guard's output is never discarded) --- guards/confidence/internal/judge/judge.go | 20 +- guards/confidence/main.go | 17 +- guards/integrity/internal/judge/judge.go | 4 + guards/integrity/main.go | 20 +- guards/policy/internal/judge/judge.go | 15 +- guards/policy/main.go | 17 +- guards/policy/main_test.go | 77 ++++++++ sdk/guard/guard.go | 26 +++ sdk/guard/server.go | 7 + sdk/guard/v1/guard.pb.go | 213 +++++++++++++++++++--- sdk/judgegate/record.go | 84 +++++++++ sdk/systemone/systemone.go | 10 + 12 files changed, 463 insertions(+), 47 deletions(-) create mode 100644 guards/policy/main_test.go create mode 100644 sdk/judgegate/record.go diff --git a/guards/confidence/internal/judge/judge.go b/guards/confidence/internal/judge/judge.go index b011772..fefddf8 100644 --- a/guards/confidence/internal/judge/judge.go +++ b/guards/confidence/internal/judge/judge.go @@ -81,6 +81,11 @@ type Outcome struct { Gap string // Read is how many results the agent read. Read int + // Called says whether a model was asked. A diagnosis with nothing read + // behind it is settled without one. + Called bool + // Call is what the judge was asked and returned, set even when it failed. + Call judgegate.Call } // Assess asks whether the evidence supports the diagnosis. A diagnosis with @@ -94,11 +99,12 @@ func (j *Judge) Assess(ctx context.Context, c Case) (Outcome, error) { shown := c.Evidence[max(0, len(c.Evidence)-maxEvidence):] state := map[string]any{"diagnosis": c.Diagnosis, "evidence": clip(shown), "action": c.Action} res, err := j.client.Classify(ctx, state, j.questions) + call := judgegate.CallOf(j.client.Model, "", res) if err != nil { - return Outcome{}, fmt.Errorf("judge: %w", err) + return Outcome{Called: true, Call: call}, fmt.Errorf("judge: %w", err) } s := res.Answers["support"] - out := Outcome{Label: s.Label(), Confidence: s.Confidence, Read: len(c.Evidence)} + out := Outcome{Label: s.Label(), Confidence: s.Confidence, Read: len(c.Evidence), Called: true, Call: call} if g := res.Answers["gap"].Label(); g != "" && g != "none" { out.Gap = g } @@ -119,7 +125,15 @@ func clip(in []Evidence) []Evidence { // Verdict turns what the judge found into a level and its reason. A supported // diagnosis acts quietly, a partly supported one is reported and goes ahead, // and an unsupported one waits for a person. -func (o Outcome) Verdict() guard.Verdict { +func (o Outcome) Verdict(st judgegate.Standing) guard.Verdict { + v := o.verdict() + if o.Called { + v.Judges = []guard.JudgeRecord{o.Call.Record(o.Label, o.Confidence, o.evidence(), st)} + } + return v +} + +func (o Outcome) verdict() guard.Verdict { switch o.Label { case Unsupported: return guard.Verdict{Ceiling: guard.ProposeAndWait, Findings: []guard.Finding{{ diff --git a/guards/confidence/main.go b/guards/confidence/main.go index f86c873..35f18dd 100644 --- a/guards/confidence/main.go +++ b/guards/confidence/main.go @@ -27,8 +27,9 @@ var recordedEval []byte type confidence struct { judge *judge.Judge - // advised says why the guard is advisory, empty when it counts. - advised string + // standing is the judge's recorded eval standing; the guard is advisory + // unless it is trusted. + standing judgegate.Standing } func build(cfg guard.Config) (guard.Guard, error) { @@ -48,13 +49,13 @@ func newConfidence(cfg guard.Config, evalJSON []byte, now func() time.Time) (*co if err != nil { return nil, err } - return &confidence{judge: j, advised: judgegate.AdvisoryReason(evalJSON, client.Model, now(), maxAge)}, nil + return &confidence{judge: j, standing: judgegate.StandingOf(evalJSON, client.Model, now(), maxAge)}, nil } // Describe is advisory until the recorded eval passes: the whole guard is a // model's opinion, so there is nothing else to count. func (c *confidence) Describe() guard.Description { - return guard.Description{Name: "confidence", Version: "1.0.0", Advisory: c.advised != ""} + return guard.Description{Name: "confidence", Version: "1.0.0", Advisory: !c.standing.Trusted} } func (c *confidence) Judge(ctx context.Context, a guard.Action) (guard.Verdict, error) { @@ -64,11 +65,11 @@ func (c *confidence) Judge(ctx context.Context, a guard.Action) (guard.Verdict, } out, err := c.judge.Assess(ctx, tc) if err != nil { - return guard.Verdict{}, err + return judgegate.FailedVerdict(out.Call.Failed(err, c.standing)), nil } - v := out.Verdict() - if c.advised != "" { - v.BlindSpots = append(v.BlindSpots, "advisory, so it sets no ceiling: "+c.advised) + v := out.Verdict(c.standing) + if !c.standing.Trusted { + v.BlindSpots = append(v.BlindSpots, "advisory, so it sets no ceiling: "+c.standing.Reason) } return v, nil } diff --git a/guards/integrity/internal/judge/judge.go b/guards/integrity/internal/judge/judge.go index 49b36c0..580bb5e 100644 --- a/guards/integrity/internal/judge/judge.go +++ b/guards/integrity/internal/judge/judge.go @@ -102,6 +102,8 @@ type Verdict struct { Validity Choice Signals map[string]float64 // rule id -> probability that the finding is real Usage *systemone.Usage + // Answers is the service's answers as JSON, kept whole for the audit. + Answers []byte // ResponseID is the service's own id for the call, kept for tracing. ResponseID string // Deployment names the endpoint the judge was reached through, for example @@ -164,6 +166,7 @@ func (s SystemOne) Judge(ctx context.Context, b *audit.Bundle, rep *audit.Report v.Usage = res.Usage if err != nil { // Fail closed: the deterministic verdict stands. + v.ResponseID = res.ID v.Error = err.Error() return v } @@ -176,6 +179,7 @@ func (s SystemOne) Judge(ctx context.Context, b *audit.Bundle, rep *audit.Report if res.ID != "" { v.ResponseID = res.ID } + v.Answers = res.AnswersJSON() if res.Model != "" { v.Model = res.Model } diff --git a/guards/integrity/main.go b/guards/integrity/main.go index 72dbeec..cbe9c42 100644 --- a/guards/integrity/main.go +++ b/guards/integrity/main.go @@ -15,6 +15,7 @@ package main import ( "context" _ "embed" + "errors" "fmt" "time" @@ -34,6 +35,8 @@ type integrity struct { opts judge.Options now func() time.Time advised string + // standing is the judge's recorded eval standing. + standing judgegate.Standing } func build(cfg guard.Config) (guard.Guard, error) { @@ -64,7 +67,8 @@ func newIntegrity(cfg guard.Config, evalJSON []byte, now func() time.Time) (*int } g.judge = judge.SystemOne{Client: client} g.opts.MinConfidence = minConf - g.advised = judgegate.AdvisoryReason(evalJSON, client.Model, g.now(), maxAge) + g.standing = judgegate.StandingOf(evalJSON, client.Model, g.now(), maxAge) + g.advised = g.standing.Reason if g.advised == "" { g.opts.Authority = judge.AuthoritySignals } @@ -87,6 +91,7 @@ func (g *integrity) Judge(ctx context.Context, a guard.Action) (guard.Verdict, e } else { answer := g.judge.Judge(ctx, b, rep, g.opts) judge.Apply(rep, answer) + v.Judges = append(v.Judges, judgeRecord(answer, g.standing)) switch { case !answer.Ok(): v.BlindSpots = append(v.BlindSpots, "the judge was unreachable, so the lens decided alone: "+answer.Error) @@ -106,6 +111,19 @@ func (g *integrity) Judge(ctx context.Context, a guard.Action) (guard.Verdict, e return v, nil } +// judgeRecord keeps the judge's whole answer, a failed call included. +func judgeRecord(a judge.Verdict, st judgegate.Standing) guard.JudgeRecord { + call := judgegate.Call{Model: a.Model, ResultID: a.ResponseID, Answers: a.Answers} + if !a.Ok() { + return call.Failed(errors.New(a.Error), st) + } + reason := "legitimacy " + a.Legitimacy.Value + if a.Validity.Value != "" { + reason += "; validity " + a.Validity.Value + } + return call.Record(a.Legitimacy.Value, a.Legitimacy.Confidence, reason, st) +} + // ceilingOf holds a proven violation for someone with authority and a signal // at propose and wait. func ceilingOf(f audit.Finding) guard.Ceiling { diff --git a/guards/policy/internal/judge/judge.go b/guards/policy/internal/judge/judge.go index 6c62626..1966e7b 100644 --- a/guards/policy/internal/judge/judge.go +++ b/guards/policy/internal/judge/judge.go @@ -85,6 +85,8 @@ type Outcome struct { Confidence float64 // Rule is the policy rule the answer rests on, empty for none. Rule string + // Call is what the judge was asked and returned, set even when it failed. + Call judgegate.Call } // Assess asks the judge whether the action breaks the policy. A violation the @@ -92,11 +94,12 @@ type Outcome struct { func (j *Judge) Assess(ctx context.Context, a judgegate.Action) (Outcome, error) { state := map[string]any{"policy": j.rules, "action": a} res, err := j.client.Classify(ctx, state, j.questions) + call := judgegate.CallOf(j.client.Model, strings.Join(j.rules, "\n"), res) if err != nil { - return Outcome{}, fmt.Errorf("judge: %w", err) + return Outcome{Call: call}, fmt.Errorf("judge: %w", err) } v := res.Answers["verdict"] - out := Outcome{Label: v.Label(), Confidence: v.Confidence} + out := Outcome{Label: v.Label(), Confidence: v.Confidence, Call: call} if out.Label == Violates && out.Confidence > 0 && out.Confidence < j.minConfidence { out.Label = Unclear } @@ -112,7 +115,13 @@ func (j *Judge) Assess(ctx context.Context, a judgegate.Action) (Outcome, error) // Verdict turns what the judge found into a level and its reason. A complying // action acts quietly, an unclear one is reported and goes ahead, and a // violation waits for a person. -func (o Outcome) Verdict() guard.Verdict { +func (o Outcome) Verdict(st judgegate.Standing) guard.Verdict { + v := o.verdict() + v.Judges = []guard.JudgeRecord{o.Call.Record(o.Label, o.Confidence, o.evidence(), st)} + return v +} + +func (o Outcome) verdict() guard.Verdict { switch o.Label { case Violates: return guard.Verdict{Ceiling: guard.ProposeAndWait, Findings: []guard.Finding{{ diff --git a/guards/policy/main.go b/guards/policy/main.go index f48a997..e4ac180 100644 --- a/guards/policy/main.go +++ b/guards/policy/main.go @@ -28,8 +28,9 @@ var recordedEval []byte type policy struct { judge *judge.Judge - // advised says why the guard is advisory, empty when it counts. - advised string + // standing is the judge's recorded eval standing; the guard is advisory + // unless it is trusted. + standing judgegate.Standing } func build(cfg guard.Config) (guard.Guard, error) { @@ -57,23 +58,23 @@ func newPolicy(cfg guard.Config, evalJSON []byte, now func() time.Time) (*policy if err != nil { return nil, err } - return &policy{judge: j, advised: judgegate.AdvisoryReason(evalJSON, client.Model, now(), maxAge)}, nil + return &policy{judge: j, standing: judgegate.StandingOf(evalJSON, client.Model, now(), maxAge)}, nil } // Describe is advisory until the recorded eval passes: the whole guard is a // model's opinion, so there is nothing else to count. func (p *policy) Describe() guard.Description { - return guard.Description{Name: "policy", Version: "1.0.0", Advisory: p.advised != ""} + return guard.Description{Name: "policy", Version: "1.0.0", Advisory: !p.standing.Trusted} } func (p *policy) Judge(ctx context.Context, a guard.Action) (guard.Verdict, error) { out, err := p.judge.Assess(ctx, judgegate.ActionOf(a)) if err != nil { - return guard.Verdict{}, err + return judgegate.FailedVerdict(out.Call.Failed(err, p.standing)), nil } - v := out.Verdict() - if p.advised != "" { - v.BlindSpots = append(v.BlindSpots, "advisory, so it sets no ceiling: "+p.advised) + v := out.Verdict(p.standing) + if !p.standing.Trusted { + v.BlindSpots = append(v.BlindSpots, "advisory, so it sets no ceiling: "+p.standing.Reason) } return v, nil } diff --git a/guards/policy/main_test.go b/guards/policy/main_test.go new file mode 100644 index 0000000..4760b8e --- /dev/null +++ b/guards/policy/main_test.go @@ -0,0 +1,77 @@ +package main + +import ( + "crypto/sha256" + "encoding/hex" + "net/http" + "net/http/httptest" + "testing" + "time" + + "github.com/samcharles93/archipelago/sdk/guard" +) + +// TestEveryVerdictKeepsItsJudgeRecord guards the audit rule that a guard never +// discards the judge's output: a clean answer, a violation and a failed call +// each carry a record of the model, the answers and the policy it was judged on. +func TestEveryVerdictKeepsItsJudgeRecord(t *testing.T) { + const rules = "never delete production data" + tests := []struct { + name string + status int + body string + wantAnswer string + wantCeil guard.Ceiling + wantFailed bool + }{ + { + name: "a complying action keeps its answer", status: http.StatusOK, wantCeil: guard.ActQuietly, wantAnswer: "complies", + body: `{"id":"r1","model":"m","answers":{"verdict":{"type":"choice","choice":"complies","confidence":0.97},"rule":{"type":"choice","choice":"none"}}}`, + }, + { + name: "a violation keeps its answer", status: http.StatusOK, wantCeil: guard.ProposeAndWait, wantAnswer: "violates", + body: `{"id":"r2","model":"m","answers":{"verdict":{"type":"choice","choice":"violates","confidence":0.95},"rule":{"type":"choice","choice":"rule 1"}}}`, + }, + {name: "a failed call keeps the error", status: http.StatusBadGateway, body: "down", wantCeil: guard.ProposeAndWait, wantFailed: true}, + } + sum := sha256.Sum256([]byte(rules)) + digest := hex.EncodeToString(sum[:]) + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(tt.status) + _, _ = w.Write([]byte(tt.body)) + })) + defer srv.Close() + g, err := newPolicy(guard.Config{Settings: map[string]string{ + "policy": rules, "judge_base_url": srv.URL, "judge_model": "m", + }}, recordedEval, time.Now) + if err != nil { + t.Fatal(err) + } + v, err := g.Judge(t.Context(), guard.Action{Connector: "c", Name: "n"}) + if err != nil { + t.Fatal(err) + } + if v.Ceiling != tt.wantCeil { + t.Errorf("ceiling = %d, want %d", v.Ceiling, tt.wantCeil) + } + if len(v.Judges) != 1 { + t.Fatalf("judges = %d, want 1", len(v.Judges)) + } + j := v.Judges[0] + if j.Model != "m" || j.Basis != rules || j.BasisDigest != digest { + t.Errorf("record = %+v, want model m and the policy as basis", j) + } + if tt.wantFailed { + if j.Reason == "" || j.Answer != "" { + t.Errorf("failed record = %+v, want the error as reason", j) + } + return + } + if j.Answer != tt.wantAnswer || j.Confidence == 0 || len(j.Answers) == 0 || j.ResultID == "" { + t.Errorf("record = %+v, want answer %q with confidence, result id and answers", j, tt.wantAnswer) + } + }) + } +} diff --git a/sdk/guard/guard.go b/sdk/guard/guard.go index 3d62f83..af9d9a0 100644 --- a/sdk/guard/guard.go +++ b/sdk/guard/guard.go @@ -109,6 +109,32 @@ 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 } // Guard judges one concrete action. diff --git a/sdk/guard/server.go b/sdk/guard/server.go index 85169bf..5b4f9bf 100644 --- a/sdk/guard/server.go +++ b/sdk/guard/server.go @@ -61,6 +61,13 @@ func (s *server) Judge(ctx context.Context, req *guardv1.JudgeRequest) (*guardv1 for _, f := range v.Findings { out.Findings = append(out.Findings, &guardv1.Finding{Text: f.Text, Evidence: f.Evidence, Strength: guardv1.Strength(f.Strength)}) } + for _, j := range v.Judges { + out.Judges = append(out.Judges, &guardv1.JudgeRecord{ + Model: j.Model, ResultId: j.ResultID, Answer: j.Answer, Confidence: j.Confidence, Reason: j.Reason, + Basis: j.Basis, BasisDigest: j.BasisDigest, Answers: j.Answers, + Trusted: j.Trusted, AdvisoryReason: j.AdvisoryReason, EvalDate: j.EvalDate, + }) + } return out, nil } diff --git a/sdk/guard/v1/guard.pb.go b/sdk/guard/v1/guard.pb.go index b6d1b72..bb99248 100644 --- a/sdk/guard/v1/guard.pb.go +++ b/sdk/guard/v1/guard.pb.go @@ -814,7 +814,11 @@ type JudgeResponse struct { Ceiling Ceiling `protobuf:"varint,1,opt,name=ceiling,proto3,enum=guard.v1.Ceiling" json:"ceiling,omitempty"` Findings []*Finding `protobuf:"bytes,2,rep,name=findings,proto3" json:"findings,omitempty"` // blind_spots are what the guard could not see. - BlindSpots []string `protobuf:"bytes,3,rep,name=blind_spots,json=blindSpots,proto3" json:"blind_spots,omitempty"` + BlindSpots []string `protobuf:"bytes,3,rep,name=blind_spots,json=blindSpots,proto3" json:"blind_spots,omitempty"` + // judges is every model judgement the verdict rests on, clean answers + // included. A guard that asked a model records the answer here, so the + // verdict can be audited without asking the model again. + Judges []*JudgeRecord `protobuf:"bytes,4,rep,name=judges,proto3" json:"judges,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache } @@ -870,6 +874,149 @@ func (x *JudgeResponse) GetBlindSpots() []string { return nil } +func (x *JudgeResponse) GetJudges() []*JudgeRecord { + if x != nil { + return x.Judges + } + return nil +} + +// JudgeRecord is what one model judge answered and what it was judged on. +type JudgeRecord struct { + state protoimpl.MessageState `protogen:"open.v1"` + // model is the model that judged. + Model string `protobuf:"bytes,1,opt,name=model,proto3" json:"model,omitempty"` + // result_id identifies the judge's result with the service that ran it. + ResultId string `protobuf:"bytes,2,opt,name=result_id,json=resultId,proto3" json:"result_id,omitempty"` + // answer is the choice the judge settled on, such as "complies". + Answer string `protobuf:"bytes,3,opt,name=answer,proto3" json:"answer,omitempty"` + Confidence float64 `protobuf:"fixed64,4,opt,name=confidence,proto3" json:"confidence,omitempty"` + // reason is the judge's own reasoning, or why the call failed. + Reason string `protobuf:"bytes,5,opt,name=reason,proto3" json:"reason,omitempty"` + // basis is the text the judge was given beyond the action itself, such as + // the policy rules. basis_digest is its SHA-256 in hex. + Basis string `protobuf:"bytes,6,opt,name=basis,proto3" json:"basis,omitempty"` + BasisDigest string `protobuf:"bytes,7,opt,name=basis_digest,json=basisDigest,proto3" json:"basis_digest,omitempty"` + // answers is every question's answer as JSON: choice, probabilities and + // confidence. + Answers []byte `protobuf:"bytes,8,opt,name=answers,proto3" json:"answers,omitempty"` + // trusted says the judge has passed its recorded eval, so its verdict sets + // a ceiling. When false, advisory_reason says why. + Trusted bool `protobuf:"varint,9,opt,name=trusted,proto3" json:"trusted,omitempty"` + AdvisoryReason string `protobuf:"bytes,10,opt,name=advisory_reason,json=advisoryReason,proto3" json:"advisory_reason,omitempty"` + // eval_date is the date of the eval the judge's standing comes from. + EvalDate string `protobuf:"bytes,11,opt,name=eval_date,json=evalDate,proto3" json:"eval_date,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *JudgeRecord) Reset() { + *x = JudgeRecord{} + mi := &file_guard_v1_guard_proto_msgTypes[11] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *JudgeRecord) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*JudgeRecord) ProtoMessage() {} + +func (x *JudgeRecord) ProtoReflect() protoreflect.Message { + mi := &file_guard_v1_guard_proto_msgTypes[11] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use JudgeRecord.ProtoReflect.Descriptor instead. +func (*JudgeRecord) Descriptor() ([]byte, []int) { + return file_guard_v1_guard_proto_rawDescGZIP(), []int{11} +} + +func (x *JudgeRecord) GetModel() string { + if x != nil { + return x.Model + } + return "" +} + +func (x *JudgeRecord) GetResultId() string { + if x != nil { + return x.ResultId + } + return "" +} + +func (x *JudgeRecord) GetAnswer() string { + if x != nil { + return x.Answer + } + return "" +} + +func (x *JudgeRecord) GetConfidence() float64 { + if x != nil { + return x.Confidence + } + return 0 +} + +func (x *JudgeRecord) GetReason() string { + if x != nil { + return x.Reason + } + return "" +} + +func (x *JudgeRecord) GetBasis() string { + if x != nil { + return x.Basis + } + return "" +} + +func (x *JudgeRecord) GetBasisDigest() string { + if x != nil { + return x.BasisDigest + } + return "" +} + +func (x *JudgeRecord) GetAnswers() []byte { + if x != nil { + return x.Answers + } + return nil +} + +func (x *JudgeRecord) GetTrusted() bool { + if x != nil { + return x.Trusted + } + return false +} + +func (x *JudgeRecord) GetAdvisoryReason() string { + if x != nil { + return x.AdvisoryReason + } + return "" +} + +func (x *JudgeRecord) GetEvalDate() string { + if x != nil { + return x.EvalDate + } + return "" +} + var File_guard_v1_guard_proto protoreflect.FileDescriptor const file_guard_v1_guard_proto_rawDesc = "" + @@ -925,12 +1072,28 @@ const file_guard_v1_guard_proto_rawDesc = "" + "\aFinding\x12\x12\n" + "\x04text\x18\x01 \x01(\tR\x04text\x12\x1a\n" + "\bevidence\x18\x02 \x01(\tR\bevidence\x12.\n" + - "\bstrength\x18\x03 \x01(\x0e2\x12.guard.v1.StrengthR\bstrength\"\x8c\x01\n" + + "\bstrength\x18\x03 \x01(\x0e2\x12.guard.v1.StrengthR\bstrength\"\xbb\x01\n" + "\rJudgeResponse\x12+\n" + "\aceiling\x18\x01 \x01(\x0e2\x11.guard.v1.CeilingR\aceiling\x12-\n" + "\bfindings\x18\x02 \x03(\v2\x11.guard.v1.FindingR\bfindings\x12\x1f\n" + "\vblind_spots\x18\x03 \x03(\tR\n" + - "blindSpots*\x95\x01\n" + + "blindSpots\x12-\n" + + "\x06judges\x18\x04 \x03(\v2\x15.guard.v1.JudgeRecordR\x06judges\"\xc3\x02\n" + + "\vJudgeRecord\x12\x14\n" + + "\x05model\x18\x01 \x01(\tR\x05model\x12\x1b\n" + + "\tresult_id\x18\x02 \x01(\tR\bresultId\x12\x16\n" + + "\x06answer\x18\x03 \x01(\tR\x06answer\x12\x1e\n" + + "\n" + + "confidence\x18\x04 \x01(\x01R\n" + + "confidence\x12\x16\n" + + "\x06reason\x18\x05 \x01(\tR\x06reason\x12\x14\n" + + "\x05basis\x18\x06 \x01(\tR\x05basis\x12!\n" + + "\fbasis_digest\x18\a \x01(\tR\vbasisDigest\x12\x18\n" + + "\aanswers\x18\b \x01(\fR\aanswers\x12\x18\n" + + "\atrusted\x18\t \x01(\bR\atrusted\x12'\n" + + "\x0fadvisory_reason\x18\n" + + " \x01(\tR\x0eadvisoryReason\x12\x1b\n" + + "\teval_date\x18\v \x01(\tR\bevalDate*\x95\x01\n" + "\rReversibility\x12\x1d\n" + "\x19REVERSIBILITY_UNSPECIFIED\x10\x00\x12&\n" + "\"REVERSIBILITY_UNDONE_AUTOMATICALLY\x10\x01\x12\x1d\n" + @@ -968,7 +1131,7 @@ func file_guard_v1_guard_proto_rawDescGZIP() []byte { } var file_guard_v1_guard_proto_enumTypes = make([]protoimpl.EnumInfo, 3) -var file_guard_v1_guard_proto_msgTypes = make([]protoimpl.MessageInfo, 13) +var file_guard_v1_guard_proto_msgTypes = make([]protoimpl.MessageInfo, 14) var file_guard_v1_guard_proto_goTypes = []any{ (Reversibility)(0), // 0: guard.v1.Reversibility (Ceiling)(0), // 1: guard.v1.Ceiling @@ -984,35 +1147,37 @@ var file_guard_v1_guard_proto_goTypes = []any{ (*Evidence)(nil), // 11: guard.v1.Evidence (*Finding)(nil), // 12: guard.v1.Finding (*JudgeResponse)(nil), // 13: guard.v1.JudgeResponse - nil, // 14: guard.v1.ConfigureRequest.SettingsEntry - nil, // 15: guard.v1.ConfigureRequest.SecretsEntry - (*durationpb.Duration)(nil), // 16: google.protobuf.Duration - (*timestamppb.Timestamp)(nil), // 17: google.protobuf.Timestamp + (*JudgeRecord)(nil), // 14: guard.v1.JudgeRecord + nil, // 15: guard.v1.ConfigureRequest.SettingsEntry + nil, // 16: guard.v1.ConfigureRequest.SecretsEntry + (*durationpb.Duration)(nil), // 17: google.protobuf.Duration + (*timestamppb.Timestamp)(nil), // 18: google.protobuf.Timestamp } var file_guard_v1_guard_proto_depIdxs = []int32{ - 14, // 0: guard.v1.ConfigureRequest.settings:type_name -> guard.v1.ConfigureRequest.SettingsEntry - 15, // 1: guard.v1.ConfigureRequest.secrets:type_name -> guard.v1.ConfigureRequest.SecretsEntry + 15, // 0: guard.v1.ConfigureRequest.settings:type_name -> guard.v1.ConfigureRequest.SettingsEntry + 16, // 1: guard.v1.ConfigureRequest.secrets:type_name -> guard.v1.ConfigureRequest.SecretsEntry 0, // 2: guard.v1.Effect.reversibility:type_name -> guard.v1.Reversibility 8, // 3: guard.v1.JudgeRequest.target:type_name -> guard.v1.Target 7, // 4: guard.v1.JudgeRequest.effect:type_name -> guard.v1.Effect 9, // 5: guard.v1.JudgeRequest.run:type_name -> guard.v1.RunContext - 16, // 6: guard.v1.JudgeRequest.deadline:type_name -> google.protobuf.Duration - 17, // 7: guard.v1.JudgeRequest.at:type_name -> google.protobuf.Timestamp + 17, // 6: guard.v1.JudgeRequest.deadline:type_name -> google.protobuf.Duration + 18, // 7: guard.v1.JudgeRequest.at:type_name -> google.protobuf.Timestamp 11, // 8: guard.v1.JudgeRequest.evidence:type_name -> guard.v1.Evidence 2, // 9: guard.v1.Finding.strength:type_name -> guard.v1.Strength 1, // 10: guard.v1.JudgeResponse.ceiling:type_name -> guard.v1.Ceiling 12, // 11: guard.v1.JudgeResponse.findings:type_name -> guard.v1.Finding - 3, // 12: guard.v1.GuardService.Configure:input_type -> guard.v1.ConfigureRequest - 5, // 13: guard.v1.GuardService.Describe:input_type -> guard.v1.DescribeRequest - 10, // 14: guard.v1.GuardService.Judge:input_type -> guard.v1.JudgeRequest - 4, // 15: guard.v1.GuardService.Configure:output_type -> guard.v1.ConfigureResponse - 6, // 16: guard.v1.GuardService.Describe:output_type -> guard.v1.DescribeResponse - 13, // 17: guard.v1.GuardService.Judge:output_type -> guard.v1.JudgeResponse - 15, // [15:18] is the sub-list for method output_type - 12, // [12:15] is the sub-list for method input_type - 12, // [12:12] is the sub-list for extension type_name - 12, // [12:12] is the sub-list for extension extendee - 0, // [0:12] is the sub-list for field type_name + 14, // 12: guard.v1.JudgeResponse.judges:type_name -> guard.v1.JudgeRecord + 3, // 13: guard.v1.GuardService.Configure:input_type -> guard.v1.ConfigureRequest + 5, // 14: guard.v1.GuardService.Describe:input_type -> guard.v1.DescribeRequest + 10, // 15: guard.v1.GuardService.Judge:input_type -> guard.v1.JudgeRequest + 4, // 16: guard.v1.GuardService.Configure:output_type -> guard.v1.ConfigureResponse + 6, // 17: guard.v1.GuardService.Describe:output_type -> guard.v1.DescribeResponse + 13, // 18: guard.v1.GuardService.Judge:output_type -> guard.v1.JudgeResponse + 16, // [16:19] is the sub-list for method output_type + 13, // [13:16] is the sub-list for method input_type + 13, // [13:13] is the sub-list for extension type_name + 13, // [13:13] is the sub-list for extension extendee + 0, // [0:13] is the sub-list for field type_name } func init() { file_guard_v1_guard_proto_init() } @@ -1026,7 +1191,7 @@ func file_guard_v1_guard_proto_init() { GoPackagePath: reflect.TypeOf(x{}).PkgPath(), RawDescriptor: unsafe.Slice(unsafe.StringData(file_guard_v1_guard_proto_rawDesc), len(file_guard_v1_guard_proto_rawDesc)), NumEnums: 3, - NumMessages: 13, + NumMessages: 14, NumExtensions: 0, NumServices: 1, }, diff --git a/sdk/judgegate/record.go b/sdk/judgegate/record.go new file mode 100644 index 0000000..093d98c --- /dev/null +++ b/sdk/judgegate/record.go @@ -0,0 +1,84 @@ +package judgegate + +import ( + "crypto/sha256" + "encoding/hex" + "time" + + "github.com/samcharles93/archipelago/sdk/guard" + "github.com/samcharles93/archipelago/sdk/systemone" +) + +// Standing is a judge's standing from the recorded eval: whether its verdicts +// count, and if not, why. +type Standing struct { + Trusted bool + Reason string + EvalDate string +} + +// StandingOf reads a shipped evaluation result and says where it leaves model at +// now. An unreadable result leaves the judge untrusted, with the cause as reason. +func StandingOf(evalJSON []byte, model string, now time.Time, maxAge time.Duration) Standing { + s := Standing{Reason: AdvisoryReason(evalJSON, model, now, maxAge)} + s.Trusted = s.Reason == "" + if rec, err := ParseRecord(evalJSON); err == nil { + s.EvalDate = rec.Date + } + return s +} + +// Call is one judge call: who answered, with what result id, and what it was +// judged on beyond the action. +type Call struct { + Model string + ResultID string + // Answers is the service's answers as JSON. + Answers []byte + // Basis is the text the judge was given beyond the action. + Basis string +} + +// CallOf describes a call made to model that returned res, whether or not it +// succeeded: a failed call still names the model and the basis it was given. +func CallOf(model, basis string, res systemone.Result) Call { + c := Call{Model: model, ResultID: res.ID, Basis: basis} + if res.Model != "" { + c.Model = res.Model + } + if len(res.Answers) > 0 { + c.Answers = res.AnswersJSON() + } + return c +} + +// Record is what the call answered, kept whole so the verdict can be audited +// without asking the model again. +func (c Call) Record(answer string, confidence float64, reason string, st Standing) guard.JudgeRecord { + r := guard.JudgeRecord{ + Model: c.Model, ResultID: c.ResultID, Answer: answer, Confidence: confidence, Reason: reason, + Basis: c.Basis, Answers: c.Answers, + Trusted: st.Trusted, AdvisoryReason: st.Reason, EvalDate: st.EvalDate, + } + if c.Basis != "" { + sum := sha256.Sum256([]byte(c.Basis)) + r.BasisDigest = hex.EncodeToString(sum[:]) + } + return r +} + +// Failed is the record of a call that errored: the error is the reason. +func (c Call) Failed(err error, st Standing) guard.JudgeRecord { + return c.Record("", 0, "the judge call failed: "+err.Error(), st) +} + +// FailedVerdict is what a guard answers when its judge could not: the action +// holds at propose and wait, as an error would hold it, and the record keeps +// what was attempted. +func FailedVerdict(rec guard.JudgeRecord) guard.Verdict { + return guard.Verdict{ + Ceiling: guard.ProposeAndWait, + BlindSpots: []string{rec.Reason}, + Judges: []guard.JudgeRecord{rec}, + } +} diff --git a/sdk/systemone/systemone.go b/sdk/systemone/systemone.go index f2d8a67..320a25a 100644 --- a/sdk/systemone/systemone.go +++ b/sdk/systemone/systemone.go @@ -230,6 +230,16 @@ type Result struct { Latency time.Duration `json:"-"` } +// AnswersJSON is every answer as JSON, for a record that keeps what the judge +// said whole: choices, probabilities and confidences. +func (r Result) AnswersJSON() json.RawMessage { + out, err := json.Marshal(r.Answers) + if err != nil { + return nil + } + return out +} + // Client is a System One endpoint. type Client struct { // BaseURL is the API root including its version segment. OpenRouter's System