457 lines
13 KiB
Go
457 lines
13 KiB
Go
// Package decisions speaks the OpenAI Decisions API: one input, typed
|
|
// questions, and answers carrying choices, scores or predicate probabilities.
|
|
//
|
|
// It maps the same question set the guards already ask a System One endpoint
|
|
// onto the Decisions API: a choice becomes a choice, a score becomes a score
|
|
// with its levels, and a bool becomes a predicate. The result is the System One
|
|
// result shape, so a guard reads both backends the same way.
|
|
package decisions
|
|
|
|
import (
|
|
"bytes"
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"io"
|
|
"net/http"
|
|
"net/url"
|
|
"sort"
|
|
"strings"
|
|
"time"
|
|
|
|
"github.com/samcharles93/archipelago/sdk/systemone"
|
|
)
|
|
|
|
const (
|
|
// DefaultBaseURL is the OpenAI API root.
|
|
DefaultBaseURL = "https://api.openai.com/v1"
|
|
// DefaultModel is the model asked when the operator names none.
|
|
DefaultModel = "gpt-6-luna"
|
|
)
|
|
|
|
// Client is an OpenAI Decisions endpoint.
|
|
type Client struct {
|
|
// BaseURL is the API root including its version segment.
|
|
BaseURL string
|
|
Model string
|
|
// APIKey is sent as a bearer token when set. It is never recorded.
|
|
APIKey string
|
|
// Label names the deployment in reports.
|
|
Label string
|
|
// HTTP is optional; a 30s-timeout client is used when nil.
|
|
HTTP *http.Client
|
|
}
|
|
|
|
// ModelID is the model this client asks.
|
|
func (c Client) ModelID() string { return c.Model }
|
|
|
|
// Deployment names the endpoint in reports.
|
|
func (c Client) Deployment() string { return c.Label }
|
|
|
|
// Endpoint resolves the decision URL: "decisions" is appended to the base URL,
|
|
// so .../v1 becomes .../v1/decisions.
|
|
func (c Client) Endpoint() string {
|
|
base := c.BaseURL
|
|
if base == "" {
|
|
base = DefaultBaseURL
|
|
}
|
|
return strings.TrimRight(base, "/") + "/decisions"
|
|
}
|
|
|
|
// Classify asks every question about state in one request.
|
|
//
|
|
// The raw request and response are returned with every result, including on a
|
|
// failed call, so the caller can record what was asked and whatever came back.
|
|
// A refusal is an error: the model declined to answer, so the call failed.
|
|
func (c Client) Classify(ctx context.Context, state any, questions map[string]systemone.Question) (systemone.Result, error) {
|
|
if c.Model == "" {
|
|
return systemone.Result{}, errors.New("decisions: model is required")
|
|
}
|
|
if len(questions) == 0 {
|
|
return systemone.Result{}, errors.New("decisions: at least one question is required")
|
|
}
|
|
wire, err := questionWires(questions)
|
|
if err != nil {
|
|
return systemone.Result{}, err
|
|
}
|
|
body, err := json.Marshal(map[string]any{
|
|
"model": c.Model,
|
|
"input": RenderInput(state),
|
|
"questions": wire,
|
|
})
|
|
if err != nil {
|
|
return systemone.Result{}, fmt.Errorf("decisions: encode request: %w", err)
|
|
}
|
|
|
|
endpoint := c.Endpoint()
|
|
result := systemone.Result{
|
|
Request: body, EndpointPath: endpointPath(endpoint), Model: c.Model, Provider: c.Label,
|
|
}
|
|
ctx, cancel := context.WithTimeout(ctx, 60*time.Second)
|
|
defer cancel()
|
|
req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(body))
|
|
if err != nil {
|
|
return result, fmt.Errorf("decisions: build request: %w", err)
|
|
}
|
|
req.Header.Set("Content-Type", "application/json")
|
|
if c.APIKey != "" {
|
|
req.Header.Set("Authorization", "Bearer "+c.APIKey)
|
|
}
|
|
|
|
httpClient := c.HTTP
|
|
if httpClient == nil {
|
|
httpClient = &http.Client{Timeout: 30 * time.Second}
|
|
}
|
|
start := time.Now()
|
|
resp, err := httpClient.Do(req)
|
|
if err != nil {
|
|
result.Latency = time.Since(start)
|
|
return result, fmt.Errorf("decisions: %s: %w", c.Label, err)
|
|
}
|
|
defer func() { _ = resp.Body.Close() }()
|
|
|
|
result.Latency = time.Since(start)
|
|
result.HTTPStatus = resp.StatusCode
|
|
payload, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
|
|
result.Response = payload
|
|
if err != nil {
|
|
return result, fmt.Errorf("decisions: read response: %w", err)
|
|
}
|
|
if resp.StatusCode < 200 || resp.StatusCode > 299 {
|
|
return result, fmt.Errorf("decisions: %s returned HTTP %d: %s",
|
|
c.Label, resp.StatusCode, truncate(string(payload), 300))
|
|
}
|
|
|
|
var decoded response
|
|
if err := json.Unmarshal(payload, &decoded); err != nil {
|
|
return result, fmt.Errorf("decisions: decode response: %w", err)
|
|
}
|
|
result.ID = decoded.ID
|
|
if decoded.Model != "" {
|
|
result.Model = decoded.Model
|
|
}
|
|
result.Usage = decoded.Usage
|
|
|
|
answers, answerErr := answersOf(decoded.Answers)
|
|
result.Answers = answers
|
|
if answerErr != nil {
|
|
return result, answerErr
|
|
}
|
|
if err := checkAnswers(answers, questions); err != nil {
|
|
return result, err
|
|
}
|
|
return result, nil
|
|
}
|
|
|
|
// response is the Decisions API response body.
|
|
type response struct {
|
|
ID string `json:"id"`
|
|
Model string `json:"model"`
|
|
Answers []answer `json:"answers"`
|
|
Usage *systemone.Usage `json:"usage"`
|
|
}
|
|
|
|
type answer struct {
|
|
Type string `json:"type"`
|
|
Name string `json:"name"`
|
|
Choice string `json:"choice"`
|
|
Confidence float64 `json:"confidence"`
|
|
Score *float64 `json:"score"`
|
|
Probability *float64 `json:"probability"`
|
|
Probabilities json.RawMessage `json:"probabilities"`
|
|
}
|
|
|
|
// answersOf converts the Decisions answers into the shared answer shape. A
|
|
// refusal stops the conversion: the call failed, and the response that says so
|
|
// is kept by the caller.
|
|
func answersOf(list []answer) (map[string]systemone.Answer, error) {
|
|
out := make(map[string]systemone.Answer, len(list))
|
|
for _, a := range list {
|
|
if a.Type == "refusal" {
|
|
return out, fmt.Errorf("decisions: the model refused question %q", a.Name)
|
|
}
|
|
converted, err := answerOf(a)
|
|
if err != nil {
|
|
return out, err
|
|
}
|
|
out[a.Name] = converted
|
|
}
|
|
return out, nil
|
|
}
|
|
|
|
// answerOf maps one answer into the shared shape, using the wire names System
|
|
// One uses so the guards read both backends identically.
|
|
func answerOf(a answer) (systemone.Answer, error) {
|
|
out := systemone.Answer{
|
|
Choice: a.Choice, Confidence: a.Confidence, Score: a.Score, Probability: a.Probability,
|
|
}
|
|
if len(a.Probabilities) > 0 {
|
|
if p, ok := probabilities(a.Probabilities); ok {
|
|
out.Probabilities = p
|
|
}
|
|
}
|
|
switch a.Type {
|
|
case "choice":
|
|
if a.Choice == "" {
|
|
return out, fmt.Errorf("decisions: answer for %q has no choice", a.Name)
|
|
}
|
|
out.Type = systemone.QuestionChoice
|
|
case "score":
|
|
if a.Score == nil {
|
|
return out, fmt.Errorf("decisions: answer for %q has no score", a.Name)
|
|
}
|
|
out.Type = systemone.QuestionScore
|
|
case "predicate":
|
|
if a.Probability == nil {
|
|
return out, fmt.Errorf("decisions: answer for %q has no probability", a.Name)
|
|
}
|
|
// "noul" is the shared wire name for a boolean answer.
|
|
out.Type = systemone.WireType(systemone.QuestionBool)
|
|
default:
|
|
return out, fmt.Errorf("decisions: unknown answer type %q for %q", a.Type, a.Name)
|
|
}
|
|
return out, nil
|
|
}
|
|
|
|
// probabilities accepts either a label-to-probability object or the service's
|
|
// list of value, label and probability, whichever the deployment returns.
|
|
func probabilities(raw json.RawMessage) (map[string]float64, bool) {
|
|
var object map[string]float64
|
|
if err := json.Unmarshal(raw, &object); err == nil {
|
|
return object, true
|
|
}
|
|
var list []struct {
|
|
Value any `json:"value"`
|
|
Label string `json:"label"`
|
|
Probability float64 `json:"probability"`
|
|
}
|
|
if err := json.Unmarshal(raw, &list); err != nil {
|
|
return nil, false
|
|
}
|
|
out := make(map[string]float64, len(list))
|
|
for _, p := range list {
|
|
key := p.Label
|
|
if key == "" {
|
|
key = fmt.Sprint(p.Value)
|
|
}
|
|
out[key] = p.Probability
|
|
}
|
|
return out, true
|
|
}
|
|
|
|
// checkAnswers fails closed on an incomplete answer set, so a partial response
|
|
// is never read as an approval.
|
|
func checkAnswers(answers map[string]systemone.Answer, questions map[string]systemone.Question) error {
|
|
if len(answers) == 0 {
|
|
return errors.New("decisions: the model returned no answers")
|
|
}
|
|
for id, q := range questions {
|
|
answer, ok := answers[id]
|
|
if !ok {
|
|
return fmt.Errorf("decisions: no answer for question %q", id)
|
|
}
|
|
if want := systemone.WireType(q.Type); answer.Type != want {
|
|
return fmt.Errorf("decisions: answer for %q has type %q, want %q", id, answer.Type, want)
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
type wireQuestion struct {
|
|
Type string `json:"type"`
|
|
Name string `json:"name"`
|
|
Instructions string `json:"instructions"`
|
|
Choices []wireChoice `json:"choices,omitempty"`
|
|
Levels []wireLevel `json:"levels,omitempty"`
|
|
}
|
|
|
|
type wireChoice struct {
|
|
Value string `json:"value"`
|
|
Description string `json:"description"`
|
|
}
|
|
|
|
type wireLevel struct {
|
|
Label string `json:"label"`
|
|
Description string `json:"description"`
|
|
}
|
|
|
|
// questionWires renders the questions in a stable order.
|
|
func questionWires(questions map[string]systemone.Question) ([]wireQuestion, error) {
|
|
ids := make([]string, 0, len(questions))
|
|
for id := range questions {
|
|
ids = append(ids, id)
|
|
}
|
|
sort.Strings(ids)
|
|
out := make([]wireQuestion, 0, len(ids))
|
|
for _, id := range ids {
|
|
q := questions[id]
|
|
if strings.TrimSpace(q.Instructions) == "" {
|
|
return nil, fmt.Errorf("decisions: question %q needs instructions", id)
|
|
}
|
|
wire := wireQuestion{Name: id, Instructions: q.Instructions}
|
|
switch q.Type {
|
|
case systemone.QuestionChoice:
|
|
criteria, ok := q.Criteria.(map[string]string)
|
|
if !ok || len(criteria) < 2 {
|
|
return nil, fmt.Errorf("decisions: question %q needs at least two choices", id)
|
|
}
|
|
wire.Type = "choice"
|
|
wire.Choices = choiceWires(criteria)
|
|
case systemone.QuestionScore:
|
|
levels, ok := q.Criteria.([]string)
|
|
if !ok || len(levels) < 2 {
|
|
return nil, fmt.Errorf("decisions: question %q needs at least two levels", id)
|
|
}
|
|
wire.Type = "score"
|
|
wire.Levels = levelWires(levels)
|
|
case systemone.QuestionBool:
|
|
criteria, ok := q.Criteria.(map[string]string)
|
|
if !ok || criteria["true"] == "" || criteria["false"] == "" {
|
|
return nil, fmt.Errorf("decisions: question %q needs both criteria", id)
|
|
}
|
|
wire.Type = "predicate"
|
|
wire.Instructions = predicateInstructions(q.Instructions, criteria)
|
|
default:
|
|
return nil, fmt.Errorf("decisions: question %q has unknown type %q", id, q.Type)
|
|
}
|
|
out = append(out, wire)
|
|
}
|
|
return out, nil
|
|
}
|
|
|
|
func choiceWires(criteria map[string]string) []wireChoice {
|
|
keys := make([]string, 0, len(criteria))
|
|
for key := range criteria {
|
|
keys = append(keys, key)
|
|
}
|
|
sort.Strings(keys)
|
|
out := make([]wireChoice, 0, len(keys))
|
|
for _, key := range keys {
|
|
out = append(out, wireChoice{Value: key, Description: criteria[key]})
|
|
}
|
|
return out
|
|
}
|
|
|
|
func levelWires(levels []string) []wireLevel {
|
|
out := make([]wireLevel, 0, len(levels))
|
|
for _, level := range levels {
|
|
out = append(out, wireLevel{Label: level, Description: level})
|
|
}
|
|
return out
|
|
}
|
|
|
|
// predicateInstructions folds a bool question's two criteria into the one
|
|
// instruction a predicate carries.
|
|
func predicateInstructions(instructions string, criteria map[string]string) string {
|
|
return instructions + "\n\nThe predicate is true when: " + criteria["true"] +
|
|
"\nThe predicate is false when: " + criteria["false"]
|
|
}
|
|
|
|
// RenderInput renders the state as labelled sections for the decision input.
|
|
//
|
|
// Sections keep a model's attention on one part at a time, and a nested value
|
|
// that sections cannot make clearer is shown as indented JSON. The guards send
|
|
// structured state, so the same input is rendered the same way every run.
|
|
func RenderInput(state any) string {
|
|
raw, err := json.Marshal(state)
|
|
if err != nil {
|
|
return fmt.Sprint(state)
|
|
}
|
|
var value any
|
|
if err := json.Unmarshal(raw, &value); err != nil {
|
|
return string(raw)
|
|
}
|
|
var b strings.Builder
|
|
writeValue(&b, value, 0)
|
|
return strings.TrimSpace(b.String())
|
|
}
|
|
|
|
func writeValue(b *strings.Builder, value any, depth int) {
|
|
switch v := value.(type) {
|
|
case map[string]any:
|
|
writeMap(b, v, depth)
|
|
case []any:
|
|
for _, item := range v {
|
|
if isSimple(item) {
|
|
fmt.Fprintf(b, "%s- %s\n", indent(depth), scalar(item))
|
|
continue
|
|
}
|
|
fmt.Fprintf(b, "%s-\n", indent(depth))
|
|
writeValue(b, item, depth+1)
|
|
}
|
|
default:
|
|
if value != nil {
|
|
fmt.Fprintf(b, "%s%s\n", indent(depth), scalar(value))
|
|
}
|
|
}
|
|
}
|
|
|
|
func writeMap(b *strings.Builder, m map[string]any, depth int) {
|
|
keys := make([]string, 0, len(m))
|
|
for key := range m {
|
|
keys = append(keys, key)
|
|
}
|
|
sort.Strings(keys)
|
|
for _, key := range keys {
|
|
value := m[key]
|
|
if isSimple(value) {
|
|
fmt.Fprintf(b, "%s%s: %s\n", indent(depth), strings.ReplaceAll(key, "_", " "), scalar(value))
|
|
continue
|
|
}
|
|
fmt.Fprintf(b, "\n%s %s\n", heading(depth), strings.ToUpper(strings.ReplaceAll(key, "_", " ")))
|
|
writeValue(b, value, depth)
|
|
}
|
|
}
|
|
|
|
func isSimple(value any) bool {
|
|
switch value.(type) {
|
|
case nil, string, float64, bool:
|
|
return true
|
|
default:
|
|
return false
|
|
}
|
|
}
|
|
|
|
// scalar renders a leaf value, pretty-printing a string that is itself JSON so
|
|
// an action's input reads as structure rather than one long line.
|
|
func scalar(value any) string {
|
|
if value == nil {
|
|
return "none"
|
|
}
|
|
s, ok := value.(string)
|
|
if !ok {
|
|
return fmt.Sprint(value)
|
|
}
|
|
trimmed := strings.TrimSpace(s)
|
|
if strings.HasPrefix(trimmed, "{") || strings.HasPrefix(trimmed, "[") {
|
|
var out bytes.Buffer
|
|
if json.Indent(&out, []byte(trimmed), "", " ") == nil {
|
|
return "\n" + out.String()
|
|
}
|
|
}
|
|
return s
|
|
}
|
|
|
|
func indent(depth int) string { return strings.Repeat(" ", depth) }
|
|
|
|
func heading(depth int) string { return strings.Repeat("#", min(depth+2, 6)) }
|
|
|
|
// endpointPath is the request path without its host, which is what a stored
|
|
// record keeps.
|
|
func endpointPath(endpoint string) string {
|
|
u, err := url.Parse(endpoint)
|
|
if err != nil || u.Path == "" {
|
|
return endpoint
|
|
}
|
|
return u.Path
|
|
}
|
|
|
|
func truncate(s string, n int) string {
|
|
s = strings.TrimSpace(s)
|
|
if len(s) <= n {
|
|
return s
|
|
}
|
|
return s[:n] + "..."
|
|
}
|