Files

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] + "..."
}