@pi-in-go/pigpen-jev 0.1.0

package/libs/typesafe/libraries/pigmodel/pigmodel_test.go

@@ -0,0 +1,410 @@
+package pigmodel
+
+import (
+	"context"
+	"errors"
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/MichaelKinsy/pigpen/components/typesafe/libraries/ownmodel"
+	"github.com/MichaelKinsy/pigpen/components/typesafe/libraries/typesafe"
+)
+
+// fakeRegistry stands in for the SDK's ModelRegistry: what the host would answer.
+type fakeRegistry struct {
+	mu       sync.Mutex
+	models   map[string]map[string]any // "provider/id" -> model
+	auth     map[string]any
+	authErr  error
+	complete func(model, request, options map[string]any) map[string]any
+
+	finds     []string
+	authCalls int
+	requests  []map[string]any
+	options   []map[string]any
+	modelsIn  []map[string]any
+}
+
+func (r *fakeRegistry) Find(providerID, modelID string) map[string]any {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.finds = append(r.finds, providerID+"/"+modelID)
+	return r.models[providerID+"/"+modelID]
+}
+
+func (r *fakeRegistry) GetApiKeyAndHeaders(model map[string]any) (map[string]any, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.authCalls++
+	return r.auth, r.authErr
+}
+
+func (r *fakeRegistry) Complete(model, request, options map[string]any) map[string]any {
+	r.mu.Lock()
+	r.requests = append(r.requests, request)
+	r.options = append(r.options, options)
+	r.modelsIn = append(r.modelsIn, model)
+	fn := r.complete
+	r.mu.Unlock()
+	return fn(model, request, options)
+}
+
+func message(text string, usageIn, usageOut float64) map[string]any {
+	return map[string]any{
+		"role": "assistant", "content": []any{map[string]any{"type": "text", "text": text}},
+		"usage":      map[string]any{"input": usageIn, "output": usageOut},
+		"stopReason": "stop",
+	}
+}
+
+func newRegistry(reply func(model, request, options map[string]any) map[string]any) *fakeRegistry {
+	return &fakeRegistry{
+		models:   map[string]map[string]any{"prov/mod": {"id": "mod", "provider": "prov", "api": "some-api"}},
+		auth:     map[string]any{"ok": true, "apiKey": "key-1", "headers": map[string]any{"X-A": "b"}},
+		complete: reply,
+	}
+}
+
+func ref() Ref { return Ref{Provider: "prov", ID: "mod"} }
+
+func mustModel(t *testing.T, r Registry) *Model {
+	t.Helper()
+	m, err := New(r, ref())
+	if err != nil {
+		t.Fatal(err)
+	}
+	return m
+}
+
+func asErr[T any](t *testing.T, err error) T {
+	t.Helper()
+	var target T
+	if !errors.As(err, &target) {
+		t.Fatalf("error %T (%v) is not %T", err, err, target)
+	}
+	return target
+}
+
+func conversation() ownmodel.Request {
+	return ownmodel.Request{Messages: []ownmodel.Message{
+		{Role: ownmodel.RoleSystem, Content: "be exact"},
+		{Role: ownmodel.RoleUser, Content: "<document>x</document>"},
+	}, Schema: map[string]any{"type": "object"}}
+}
+
+func TestComplete_SendsTheConversationThroughTheRegistry(t *testing.T) {
+	r := newRegistry(func(model, request, options map[string]any) map[string]any { return message(`{"answers":{}}`, 12, 5) })
+	m := mustModel(t, r)
+	res, err := m.Complete(context.Background(), conversation())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Text != `{"answers":{}}` || res.InputTokens == nil || *res.InputTokens != 12 || res.OutputTokens == nil || *res.OutputTokens != 5 {
+		t.Fatalf("result %+v", res)
+	}
+	if m.Name() != "mod" {
+		t.Fatalf("name %q", m.Name())
+	}
+	req := r.requests[0]
+	if req["systemPrompt"] != "be exact" {
+		t.Fatalf("system prompt %v", req["systemPrompt"])
+	}
+	msgs := req["messages"].([]any)
+	if len(msgs) != 1 {
+		t.Fatalf("messages %v", msgs)
+	}
+	um := msgs[0].(map[string]any)
+	if um["role"] != "user" {
+		t.Fatalf("role %v", um["role"])
+	}
+	content := um["content"].([]any)[0].(map[string]any)
+	if content["type"] != "text" || content["text"] != "<document>x</document>" {
+		t.Fatalf("content %v", content)
+	}
+	if _, ok := um["timestamp"]; !ok {
+		t.Fatal("a Pi user message carries a timestamp")
+	}
+	if r.options[0]["apiKey"] != "key-1" || !reflect.DeepEqual(r.options[0]["headers"], map[string]any{"X-A": "b"}) {
+		t.Fatalf("options %v", r.options[0])
+	}
+	if !reflect.DeepEqual(r.modelsIn[0], r.models["prov/mod"]) {
+		t.Fatal("the model handed to Complete must be the registry's")
+	}
+}
+
+func TestComplete_ResolvesTheModelAndAuthOnFirstUseAndCachesTheModel(t *testing.T) {
+	r := newRegistry(func(model, request, options map[string]any) map[string]any { return message("x", 1, 1) })
+	m := mustModel(t, r)
+	if len(r.finds) != 0 || r.authCalls != 0 {
+		t.Fatal("New must not touch the registry")
+	}
+	for i := 0; i < 2; i++ {
+		if _, err := m.Complete(context.Background(), conversation()); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if !reflect.DeepEqual(r.finds, []string{"prov/mod"}) {
+		t.Fatalf("finds %v", r.finds)
+	}
+	if r.authCalls != 2 { // credentials are resolved per request: they can refresh
+		t.Fatalf("auth calls %d", r.authCalls)
+	}
+}
+
+func TestComplete_ReportsAModelTheRegistryDoesNotKnow(t *testing.T) {
+	r := newRegistry(func(model, request, options map[string]any) map[string]any { return message("x", 1, 1) })
+	m, err := New(r, Ref{Provider: "prov", ID: "missing"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, err = m.Complete(context.Background(), conversation())
+	asErr[*typesafe.TypeSafeError](t, err)
+	if !strings.Contains(err.Error(), "prov/missing") {
+		t.Fatalf("got %v", err)
+	}
+}
+
+func TestComplete_AuthFailuresAreReported(t *testing.T) {
+	r := newRegistry(func(model, request, options map[string]any) map[string]any { return message("x", 1, 1) })
+	r.auth = map[string]any{"ok": false, "error": `No API key found for "prov"`}
+	_, err := mustModel(t, r).Complete(context.Background(), conversation())
+	asErr[*typesafe.TypeSafeError](t, err)
+	if !strings.Contains(err.Error(), `No API key found for "prov"`) {
+		t.Fatalf("got %v", err)
+	}
+	r = newRegistry(func(model, request, options map[string]any) map[string]any { return message("x", 1, 1) })
+	r.authErr = errors.New("host down")
+	_, err = mustModel(t, r).Complete(context.Background(), conversation())
+	if err == nil || !strings.Contains(err.Error(), "host down") {
+		t.Fatalf("got %v", err)
+	}
+}
+
+func TestComplete_AssistantTurnsCarryTheModelIdentity(t *testing.T) {
+	r := newRegistry(func(model, request, options map[string]any) map[string]any { return message("x", 1, 1) })
+	req := conversation()
+	req.Messages = append(req.Messages,
+		ownmodel.Message{Role: ownmodel.RoleAssistant, Content: `{"answers":`},
+		ownmodel.Message{Role: ownmodel.RoleUser, Content: "fix it"})
+	if _, err := mustModel(t, r).Complete(context.Background(), req); err != nil {
+		t.Fatal(err)
+	}
+	msgs := r.requests[0]["messages"].([]any)
+	if len(msgs) != 3 {
+		t.Fatalf("messages %v", msgs)
+	}
+	a := msgs[1].(map[string]any)
+	if a["role"] != "assistant" || a["api"] != "some-api" || a["provider"] != "prov" || a["model"] != "mod" || a["stopReason"] != "stop" {
+		t.Fatalf("assistant message %v", a)
+	}
+	if txt := a["content"].([]any)[0].(map[string]any); txt["type"] != "text" || txt["text"] != `{"answers":` {
+		t.Fatalf("assistant content %v", txt)
+	}
+	if _, ok := a["usage"].(map[string]any); !ok {
+		t.Fatal("an assistant message carries usage")
+	}
+}
+
+func TestComplete_MultipleSystemMessagesAreJoined(t *testing.T) {
+	r := newRegistry(func(model, request, options map[string]any) map[string]any { return message("x", 1, 1) })
+	req := ownmodel.Request{Messages: []ownmodel.Message{{Role: ownmodel.RoleSystem, Content: "a"}, {Role: ownmodel.RoleSystem, Content: "b"}, {Role: ownmodel.RoleUser, Content: "u"}}}
+	if _, err := mustModel(t, r).Complete(context.Background(), req); err != nil {
+		t.Fatal(err)
+	}
+	if r.requests[0]["systemPrompt"] != "a\n\nb" {
+		t.Fatalf("system prompt %v", r.requests[0]["systemPrompt"])
+	}
+}
+
+func TestComplete_TextBlocksAreConcatenatedAndOtherBlocksIgnored(t *testing.T) {
+	r := newRegistry(func(model, request, options map[string]any) map[string]any {
+		return map[string]any{"role": "assistant", "stopReason": "stop", "content": []any{
+			map[string]any{"type": "thinking", "thinking": "hmm"},
+			map[string]any{"type": "text", "text": `{"a":`},
+			map[string]any{"type": "text", "text": `1}`},
+		}}
+	})
+	res, err := mustModel(t, r).Complete(context.Background(), conversation())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Text != `{"a":1}` || res.InputTokens != nil || res.OutputTokens != nil {
+		t.Fatalf("result %+v (unreported usage must stay unknown)", res)
+	}
+}
+
+func TestComplete_StopReasonsError(t *testing.T) {
+	cases := []struct {
+		name   string
+		reply  map[string]any
+		check  func(t *testing.T, err error)
+		retrys bool
+	}{
+		{"status in the message", map[string]any{"stopReason": "error", "errorMessage": "429 rate limited"}, func(t *testing.T, err error) {
+			asErr[*typesafe.RateLimitError](t, err)
+		}, true},
+		{"server status", map[string]any{"stopReason": "error", "errorMessage": "503 upstream"}, func(t *testing.T, err error) {
+			asErr[*typesafe.InternalServerError](t, err)
+		}, true},
+		{"client status", map[string]any{"stopReason": "error", "errorMessage": "401 bad key"}, func(t *testing.T, err error) {
+			asErr[*typesafe.AuthenticationError](t, err)
+		}, false},
+		{"no status", map[string]any{"stopReason": "error", "errorMessage": "socket hang up"}, func(t *testing.T, err error) {
+			asErr[*typesafe.APIConnectionError](t, err)
+			if !strings.Contains(err.Error(), "socket hang up") {
+				t.Fatalf("got %v", err)
+			}
+		}, true},
+		{"no message", map[string]any{"stopReason": "error"}, func(t *testing.T, err error) { asErr[*typesafe.APIConnectionError](t, err) }, true},
+	}
+	for _, tc := range cases {
+		r := newRegistry(func(model, request, options map[string]any) map[string]any { return tc.reply })
+		_, err := mustModel(t, r).Complete(context.Background(), conversation())
+		if err == nil {
+			t.Fatalf("%s: want an error", tc.name)
+		}
+		tc.check(t, err)
+		policy := typesafe.DefaultRetryPolicy()
+		calls := 0
+		_, _ = typesafe.Retry(context.Background(), func() typesafe.RetryPolicy { policy.BackoffInitial = 0; return policy }(), typesafe.RetryHooks{}, func(ctx context.Context, attempt int) (int, error) {
+			calls++
+			_, err := mustModel(t, r).Complete(ctx, conversation())
+			return 0, err
+		})
+		if (calls > 1) != tc.retrys {
+			t.Fatalf("%s: retried=%v, want %v", tc.name, calls > 1, tc.retrys)
+		}
+	}
+}
+
+func TestComplete_StopReasonsNotAnswers(t *testing.T) {
+	for reason, want := range map[string]string{
+		"length":  "output",
+		"toolUse": "tool",
+		"weird":   `"weird"`,
+	} {
+		r := newRegistry(func(model, request, options map[string]any) map[string]any {
+			return map[string]any{"stopReason": reason, "content": []any{map[string]any{"type": "text", "text": "partial"}}}
+		})
+		_, err := mustModel(t, r).Complete(context.Background(), conversation())
+		te := asErr[*typesafe.TypeSafeError](t, err)
+		if !strings.Contains(te.Message, want) {
+			t.Fatalf("%s: %q lacks %q", reason, te.Message, want)
+		}
+		var api *typesafe.APIError
+		var conn *typesafe.APIConnectionError
+		if errors.As(err, &api) || errors.As(err, &conn) {
+			t.Fatalf("%s: must not be retryable", reason)
+		}
+	}
+	r := newRegistry(func(model, request, options map[string]any) map[string]any {
+		return map[string]any{"stopReason": "aborted"}
+	})
+	_, err := mustModel(t, r).Complete(context.Background(), conversation())
+	asErr[*typesafe.APIUserAbortError](t, err)
+	r = newRegistry(func(model, request, options map[string]any) map[string]any { return nil })
+	_, err = mustModel(t, r).Complete(context.Background(), conversation())
+	asErr[*typesafe.TypeSafeError](t, err)
+}
+
+func TestComplete_AContextThatEndsReturnsAtOnceWithoutWaitingForTheHost(t *testing.T) {
+	release := make(chan struct{})
+	r := newRegistry(func(model, request, options map[string]any) map[string]any { <-release; return message("x", 1, 1) })
+	defer close(release)
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { _, err := mustModel(t, r).Complete(ctx, conversation()); done <- err }()
+	time.Sleep(20 * time.Millisecond)
+	cancel()
+	select {
+	case err := <-done:
+		asErr[*typesafe.APIUserAbortError](t, err)
+		if !errors.Is(err, context.Canceled) {
+			t.Fatalf("the abort must carry the context error: %v", err)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("Complete did not return after the context ended")
+	}
+}
+
+func TestComplete_NativeStructuredOutputIsNotSupported(t *testing.T) {
+	r := newRegistry(func(model, request, options map[string]any) map[string]any { return message("x", 1, 1) })
+	req := conversation()
+	req.Structured = true
+	_, err := mustModel(t, r).Complete(context.Background(), req)
+	asErr[*typesafe.TypeSafeError](t, err)
+	if !strings.Contains(err.Error(), "structured") {
+		t.Fatalf("got %v", err)
+	}
+	if len(r.requests) != 0 {
+		t.Fatal("no request may be sent")
+	}
+}
+
+func TestProviderShapesOfTheModelMap(t *testing.T) {
+	// The provider may be a string or an object with an id, the model id "id" or "modelId".
+	for _, m := range []map[string]any{
+		{"id": "mod", "provider": "prov", "api": "x"},
+		{"modelId": "mod", "provider": map[string]any{"id": "prov"}, "api": "x"},
+	} {
+		r := newRegistry(func(model, request, options map[string]any) map[string]any { return message("x", 1, 1) })
+		r.models["prov/mod"] = m
+		req := conversation()
+		req.Messages = append(req.Messages, ownmodel.Message{Role: ownmodel.RoleAssistant, Content: "a"}, ownmodel.Message{Role: ownmodel.RoleUser, Content: "b"})
+		if _, err := mustModel(t, r).Complete(context.Background(), req); err != nil {
+			t.Fatal(err)
+		}
+		a := r.requests[0]["messages"].([]any)[1].(map[string]any)
+		if a["provider"] != "prov" || a["model"] != "mod" {
+			t.Fatalf("model %v -> assistant %v", m, a)
+		}
+	}
+}
+
+func TestNoProviderOrModelNamesAreBuiltIn(t *testing.T) {
+	// Provider routing is data: no source string of the own-model packages names a provider
+	// or a model family.
+	banned := []string{"openai", "anthropic", "gemini", "google", "copilot", "claude", "gpt", "bedrock", "azure", "mistral", "llama", "deepseek"}
+	for _, dir := range []string{".", filepath.Join("..", "ownmodel")} {
+		files, err := filepath.Glob(filepath.Join(dir, "*.go"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		fset := token.NewFileSet()
+		for _, file := range files {
+			if strings.HasSuffix(file, "_test.go") {
+				continue
+			}
+			src, err := os.ReadFile(file)
+			if err != nil {
+				t.Fatal(err)
+			}
+			f, err := parser.ParseFile(fset, file, src, 0) // comments are not source strings
+			if err != nil {
+				t.Fatal(err)
+			}
+			ast.Inspect(f, func(n ast.Node) bool {
+				lit, ok := n.(*ast.BasicLit)
+				if !ok || lit.Kind != token.STRING {
+					return true
+				}
+				s, _ := strconv.Unquote(lit.Value)
+				for _, b := range banned {
+					if strings.Contains(strings.ToLower(s), b) {
+						t.Errorf("%s: string %q names %q", fset.Position(lit.Pos()), s, b)
+					}
+				}
+				return true
+			})
+		}
+	}
+}

package/libs/typesafe/libraries/typesafe/answers.go

@@ -0,0 +1,268 @@
+package typesafe
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+)
+
+// Answer is the typed answer to one question: [NoulAnswer], [ChoiceAnswer] or
+// [ScoreAnswer]. An answer with an unknown type decodes as [RawAnswer].
+type Answer interface {
+	// AnswerType returns the wire type of the answer.
+	AnswerType() QuestionType
+	isAnswer()
+}
+
+// NoulAnswer is a yes/no answer.
+type NoulAnswer struct {
+	// Noul is the probability of a yes answer, from zero to one.
+	Noul float64 `json:"noul"`
+}
+
+// ChoiceAnswer is a selected label and its probabilities.
+type ChoiceAnswer struct {
+	Choice        string             `json:"choice"`
+	Confidence    float64            `json:"confidence"`
+	Probabilities map[string]float64 `json:"probabilities"`
+}
+
+// ScoreAnswer is an expected score with its rubric and probabilities.
+type ScoreAnswer struct {
+	// Score is the expected score, which may fall between integer rubric levels.
+	Score      float64 `json:"score"`
+	Confidence float64 `json:"confidence"`
+	// Legend maps a score to the rubric description that was sent for it.
+	Legend map[int]any `json:"legend"`
+	// Probabilities maps a score to its probability.
+	Probabilities map[int]float64 `json:"probabilities"`
+}
+
+// RawAnswer is an answer whose type this package does not know; Raw is the JSON as sent.
+type RawAnswer struct {
+	Type QuestionType
+	Raw  json.RawMessage
+}
+
+// AnswerType implements [Answer].
+func (NoulAnswer) AnswerType() QuestionType { return TypeNoul }
+
+// AnswerType implements [Answer].
+func (ChoiceAnswer) AnswerType() QuestionType { return TypeChoice }
+
+// AnswerType implements [Answer].
+func (ScoreAnswer) AnswerType() QuestionType { return TypeScore }
+
+// AnswerType implements [Answer].
+func (a RawAnswer) AnswerType() QuestionType { return a.Type }
+func (NoulAnswer) isAnswer()                 {}
+func (ChoiceAnswer) isAnswer()               {}
+func (ScoreAnswer) isAnswer()                {}
+func (RawAnswer) isAnswer()                  {}
+
+// MarshalJSON writes the wire form with its "type".
+func (a NoulAnswer) MarshalJSON() ([]byte, error) {
+	type plain NoulAnswer
+	return json.Marshal(struct {
+		Type QuestionType `json:"type"`
+		plain
+	}{TypeNoul, plain(a)})
+}
+
+// MarshalJSON writes the wire form with its "type".
+func (a ChoiceAnswer) MarshalJSON() ([]byte, error) {
+	type plain ChoiceAnswer
+	return json.Marshal(struct {
+		Type QuestionType `json:"type"`
+		plain
+	}{TypeChoice, plain(a)})
+}
+
+// MarshalJSON writes the wire form with its "type".
+func (a ScoreAnswer) MarshalJSON() ([]byte, error) {
+	type plain ScoreAnswer
+	return json.Marshal(struct {
+		Type QuestionType `json:"type"`
+		plain
+	}{TypeScore, plain(a)})
+}
+
+// MarshalJSON writes the JSON as it was received.
+func (a RawAnswer) MarshalJSON() ([]byte, error) { return a.Raw, nil }
+
+// Usage is the token usage of a request.
+type Usage struct {
+	InputTokens  int `json:"input_tokens"`
+	OutputTokens int `json:"output_tokens"`
+}
+
+// SystemOneResult is the answers, keyed by question name, with model and usage metadata.
+type SystemOneResult struct {
+	// Model is the model that answered the request.
+	Model   string
+	Answers map[string]Answer
+	Usage   Usage
+}
+
+func (r *SystemOneResult) answer(name string) (Answer, error) {
+	a, ok := r.Answers[name]
+	if !ok {
+		return nil, errorf("No answer named %q in the result.", name)
+	}
+	return a, nil
+}
+
+func wrongType(name string, got Answer, want QuestionType) error {
+	return errorf("Answer %q is a %s answer, not a %s answer.", name, got.AnswerType(), want)
+}
+
+// Noul returns the yes/no answer named name, or an error when it is absent or of
+// another type.
+func (r *SystemOneResult) Noul(name string) (NoulAnswer, error) {
+	a, err := r.answer(name)
+	if err != nil {
+		return NoulAnswer{}, err
+	}
+	v, ok := a.(NoulAnswer)
+	if !ok {
+		return NoulAnswer{}, wrongType(name, a, TypeNoul)
+	}
+	return v, nil
+}
+
+// Choice returns the choice answer named name, or an error when it is absent or of
+// another type.
+func (r *SystemOneResult) Choice(name string) (ChoiceAnswer, error) {
+	a, err := r.answer(name)
+	if err != nil {
+		return ChoiceAnswer{}, err
+	}
+	v, ok := a.(ChoiceAnswer)
+	if !ok {
+		return ChoiceAnswer{}, wrongType(name, a, TypeChoice)
+	}
+	return v, nil
+}
+
+// Score returns the score answer named name, or an error when it is absent or of
+// another type.
+func (r *SystemOneResult) Score(name string) (ScoreAnswer, error) {
+	a, err := r.answer(name)
+	if err != nil {
+		return ScoreAnswer{}, err
+	}
+	v, ok := a.(ScoreAnswer)
+	if !ok {
+		return ScoreAnswer{}, wrongType(name, a, TypeScore)
+	}
+	return v, nil
+}
+
+// UnmarshalJSON decodes the wire form ({model, answers, usage}); each answer is
+// decoded by its "type". Unknown fields are ignored and missing answers are not an error.
+func (r *SystemOneResult) UnmarshalJSON(data []byte) error {
+	var wire struct {
+		Model   string                     `json:"model"`
+		Answers map[string]json.RawMessage `json:"answers"`
+		Usage   Usage                      `json:"usage"`
+	}
+	if err := json.Unmarshal(data, &wire); err != nil {
+		return &TypeSafeError{Message: "Unexpected response shape; expected { model, answers, usage }: " + err.Error(), Cause: err}
+	}
+	out := SystemOneResult{Model: wire.Model, Usage: wire.Usage, Answers: make(map[string]Answer, len(wire.Answers))}
+	for name, raw := range wire.Answers {
+		a, err := decodeAnswer(raw)
+		if err != nil {
+			return &TypeSafeError{Message: fmt.Sprintf("Unexpected shape of the answer %q: %v", name, err), Cause: err}
+		}
+		out.Answers[name] = a
+	}
+	*r = out
+	return nil
+}
+
+func decodeAnswer(raw json.RawMessage) (Answer, error) {
+	var head struct {
+		Type QuestionType `json:"type"`
+	}
+	if err := json.Unmarshal(raw, &head); err != nil {
+		return nil, err
+	}
+	switch head.Type {
+	case TypeNoul:
+		var a NoulAnswer
+		return a, json.Unmarshal(raw, &a)
+	case TypeChoice:
+		var a ChoiceAnswer
+		return a, json.Unmarshal(raw, &a)
+	case TypeScore:
+		var a ScoreAnswer
+		return a, json.Unmarshal(raw, &a)
+	}
+	return RawAnswer{Type: head.Type, Raw: append(json.RawMessage(nil), raw...)}, nil
+}
+
+// MarshalJSON encodes the wire form.
+func (r SystemOneResult) MarshalJSON() ([]byte, error) {
+	names := make([]string, 0, len(r.Answers))
+	for n := range r.Answers {
+		names = append(names, n)
+	}
+	sort.Strings(names)
+	answers := newObject()
+	for _, n := range names {
+		answers.value(n, r.Answers[n])
+	}
+	raw, err := answers.done()
+	if err != nil {
+		return nil, err
+	}
+	o := newObject()
+	o.value("model", r.Model)
+	o.raw("answers", raw)
+	o.value("usage", r.Usage)
+	return o.done()
+}
+
+// ModelCard is the metadata of an available model.
+type ModelCard struct {
+	Name        string `json:"name"`
+	Description string `json:"description"`
+	ReleaseDate string `json:"release_date"`
+}
+
+// SystemOneRequest is the state and named questions for SystemOne.
+type SystemOneRequest struct {
+	// State is text, a JSON object or array, or null.
+	State Entry
+	// Questions must be non-empty.
+	Questions Questions
+	// Model overrides the client's default model when non-empty.
+	Model string
+	// Extra fields are forwarded at the top level of the request body, including nulls.
+	// The names state, questions and model are reserved.
+	Extra map[string]any
+}
+
+// MarshalJSON writes the request body: state, questions, model, then the extra fields.
+func (r SystemOneRequest) MarshalJSON() ([]byte, error) {
+	o := newObject()
+	o.entry("state", r.State)
+	o.value("questions", r.Questions)
+	if r.Model != "" {
+		o.value("model", r.Model)
+	}
+	names := make([]string, 0, len(r.Extra))
+	for n := range r.Extra {
+		names = append(names, n)
+	}
+	sort.Strings(names)
+	for _, n := range names {
+		switch n {
+		case "state", "questions", "model":
+			return nil, errorf("The extra request field %q collides with a request field of the same name.", n)
+		}
+		o.value(n, r.Extra[n])
+	}
+	return o.done()
+}