@pi-in-go/pigpen-pi-typesafe-api 0.1.0

package/json.go

@@ -0,0 +1,299 @@
+package pitypesafe
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"math"
+	"strconv"
+	"strings"
+	"unicode/utf8"
+)
+
+// The library moves JSON as a tree of nil, bool, float64, string, []any and
+// *Object. Object remembers key order the way a JavaScript object does, because
+// the order of questions, criteria and answers is observable: it decides how a
+// large request is chunked, the order the model reads Choice options in, and the
+// order answers are printed. Go maps cannot carry it.
+
+// Object is a JSON object that keeps insertion order.
+type Object struct {
+	keys []string
+	vals map[string]any
+}
+
+// NewObject returns an empty Object.
+func NewObject() *Object { return &Object{vals: map[string]any{}} }
+
+// Set stores a value. Setting an existing key keeps its position, as JavaScript does.
+func (o *Object) Set(key string, value any) {
+	if _, ok := o.vals[key]; !ok {
+		o.keys = append(o.keys, key)
+	}
+	o.vals[key] = value
+}
+
+// Get returns the value for key and whether it is present.
+func (o *Object) Get(key string) (any, bool) {
+	v, ok := o.vals[key]
+	return v, ok
+}
+
+// Has reports whether key is present.
+func (o *Object) Has(key string) bool { _, ok := o.vals[key]; return ok }
+
+// Delete removes a key.
+func (o *Object) Delete(key string) {
+	if _, ok := o.vals[key]; !ok {
+		return
+	}
+	delete(o.vals, key)
+	for i, k := range o.keys {
+		if k == key {
+			o.keys = append(o.keys[:i:i], o.keys[i+1:]...)
+			break
+		}
+	}
+}
+
+// Keys returns the keys in insertion order. The slice is a copy.
+func (o *Object) Keys() []string { return append([]string(nil), o.keys...) }
+
+// Len is the number of keys.
+func (o *Object) Len() int { return len(o.keys) }
+
+// Clone copies the object and every value below it.
+func (o *Object) Clone() *Object {
+	c := NewObject()
+	for _, k := range o.keys {
+		c.Set(k, cloneValue(o.vals[k]))
+	}
+	return c
+}
+
+func cloneValue(v any) any {
+	switch t := v.(type) {
+	case *Object:
+		return t.Clone()
+	case []any:
+		out := make([]any, len(t))
+		for i, e := range t {
+			out[i] = cloneValue(e)
+		}
+		return out
+	}
+	return v
+}
+
+// ParseJSON decodes JSON text into a tree that keeps object key order. Numbers are float64, like JavaScript's.
+func ParseJSON(data []byte) (any, error) {
+	dec := json.NewDecoder(bytes.NewReader(data))
+	dec.UseNumber()
+	v, err := parseValue(dec)
+	if err != nil {
+		return nil, err
+	}
+	if _, err := dec.Token(); !errors.Is(err, io.EOF) {
+		return nil, errors.New("unexpected data after the JSON value")
+	}
+	return v, nil
+}
+
+func parseValue(dec *json.Decoder) (any, error) {
+	tok, err := dec.Token()
+	if err != nil {
+		return nil, err
+	}
+	switch t := tok.(type) {
+	case json.Delim:
+		switch t {
+		case '{':
+			obj := NewObject()
+			for dec.More() {
+				keyTok, err := dec.Token()
+				if err != nil {
+					return nil, err
+				}
+				key, _ := keyTok.(string)
+				v, err := parseValue(dec)
+				if err != nil {
+					return nil, err
+				}
+				obj.Set(key, v)
+			}
+			if _, err := dec.Token(); err != nil {
+				return nil, err
+			}
+			return obj, nil
+		case '[':
+			arr := []any{}
+			for dec.More() {
+				v, err := parseValue(dec)
+				if err != nil {
+					return nil, err
+				}
+				arr = append(arr, v)
+			}
+			if _, err := dec.Token(); err != nil {
+				return nil, err
+			}
+			return arr, nil
+		}
+		return nil, fmt.Errorf("unexpected delimiter %q", t)
+	case json.Number:
+		f, err := strconv.ParseFloat(string(t), 64)
+		if err != nil && !math.IsInf(f, 0) {
+			return nil, err
+		}
+		return f, nil
+	default:
+		return tok, nil // string, bool, nil
+	}
+}
+
+// FromGo converts any Go value to a tree: a tree passes through, everything else takes the
+// encoding/json round trip. A value JSON cannot carry (a cycle, NaN, a function) is an error.
+func FromGo(v any) (any, error) {
+	if isTree(v) {
+		return v, nil
+	}
+	data, err := json.Marshal(v)
+	if err != nil {
+		return nil, err
+	}
+	return ParseJSON(data)
+}
+
+func isTree(v any) bool {
+	switch t := v.(type) {
+	case nil, bool, string:
+		return true
+	case float64:
+		return !math.IsNaN(t) && !math.IsInf(t, 0)
+	case *Object:
+		for _, k := range t.keys {
+			if !isTree(t.vals[k]) {
+				return false
+			}
+		}
+		return t != nil
+	case []any:
+		for _, e := range t {
+			if !isTree(e) {
+				return false
+			}
+		}
+		return true
+	}
+	return false
+}
+
+// EncodeJSON serializes a tree the way JSON.stringify does: keys in insertion order, no
+// insignificant whitespace, U+2028 and U+2029 unescaped, numbers in JavaScript's format. The
+// byte length of this text is what the input limit measures.
+func EncodeJSON(v any) ([]byte, error) {
+	var b bytes.Buffer
+	if err := encodeValue(&b, v); err != nil {
+		return nil, err
+	}
+	return b.Bytes(), nil
+}
+
+func encodeValue(b *bytes.Buffer, v any) error {
+	switch t := v.(type) {
+	case nil:
+		b.WriteString("null")
+	case bool:
+		b.WriteString(strconv.FormatBool(t))
+	case string:
+		writeJSString(b, t)
+	case float64:
+		if math.IsNaN(t) || math.IsInf(t, 0) {
+			return fmt.Errorf("cannot encode %v as JSON", t)
+		}
+		b.WriteString(jsNumber(t))
+	case *Object:
+		b.WriteByte('{')
+		for i, k := range t.keys {
+			if i > 0 {
+				b.WriteByte(',')
+			}
+			writeJSString(b, k)
+			b.WriteByte(':')
+			if err := encodeValue(b, t.vals[k]); err != nil {
+				return err
+			}
+		}
+		b.WriteByte('}')
+	case []any:
+		b.WriteByte('[')
+		for i, e := range t {
+			if i > 0 {
+				b.WriteByte(',')
+			}
+			if err := encodeValue(b, e); err != nil {
+				return err
+			}
+		}
+		b.WriteByte(']')
+	default:
+		tree, err := FromGo(v)
+		if err != nil {
+			return err
+		}
+		if isTree(tree) {
+			return encodeValue(b, tree)
+		}
+		return fmt.Errorf("cannot encode %T as JSON", v)
+	}
+	return nil
+}
+
+func writeJSString(b *bytes.Buffer, s string) {
+	b.WriteByte('"')
+	for _, r := range strings.ToValidUTF8(s, "\uFFFD") {
+		switch r {
+		case '"':
+			b.WriteString(`\"`)
+		case '\\':
+			b.WriteString(`\\`)
+		case '\b':
+			b.WriteString(`\b`)
+		case '\f':
+			b.WriteString(`\f`)
+		case '\n':
+			b.WriteString(`\n`)
+		case '\r':
+			b.WriteString(`\r`)
+		case '\t':
+			b.WriteString(`\t`)
+		default:
+			if r < 0x20 {
+				fmt.Fprintf(b, `\u%04x`, r)
+			} else {
+				var buf [utf8.UTFMax]byte
+				n := utf8.EncodeRune(buf[:], r)
+				b.Write(buf[:n])
+			}
+		}
+	}
+	b.WriteByte('"')
+}
+
+// jsNumber formats like JavaScript's Number.prototype.toString for the JSON range.
+func jsNumber(f float64) string {
+	if f == 0 {
+		return "0" // also -0
+	}
+	abs := math.Abs(f)
+	if abs >= 1e21 || abs < 1e-6 {
+		s := strconv.FormatFloat(f, 'e', -1, 64) // 1e+21, 1.5e-07
+		mant, exp, _ := strings.Cut(s, "e")
+		sign := exp[0]
+		digits := strings.TrimLeft(exp[1:], "0")
+		return mant + "e" + string(sign) + digits
+	}
+	return strconv.FormatFloat(f, 'f', -1, 64)
+}

package/json_test.go

@@ -0,0 +1,92 @@
+package pitypesafe
+
+import (
+	"math"
+	"testing"
+)
+
+func TestObjectKeepsInsertionOrderThroughParseAndEncode(t *testing.T) {
+	in := `{"z":1,"a":{"y":[true,null,"x"],"b":2},"m":"é\u2028\n"}`
+	v, err := ParseJSON([]byte(in))
+	if err != nil {
+		t.Fatal(err)
+	}
+	obj := v.(*Object)
+	if got := obj.Keys(); len(got) != 3 || got[0] != "z" || got[1] != "a" || got[2] != "m" {
+		t.Fatalf("keys = %v", got)
+	}
+	out, err := EncodeJSON(v)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// U+2028 stays raw (JSON.stringify does not escape it), newline is escaped.
+	want := "{\"z\":1,\"a\":{\"y\":[true,null,\"x\"],\"b\":2},\"m\":\"é\u2028\\n\"}"
+	if string(out) != want {
+		t.Fatalf("got %q want %q", out, want)
+	}
+}
+
+func TestEncodeJSONNumbersFollowJavaScript(t *testing.T) {
+	cases := map[float64]string{0: "0", math.Copysign(0, -1): "0", 1: "1", 0.5: "0.5", 1e21: "1e+21", 1.5e-7: "1.5e-7", 123456789012: "123456789012", -2.25: "-2.25"}
+	for in, want := range cases {
+		out, err := EncodeJSON(in)
+		if err != nil || string(out) != want {
+			t.Errorf("EncodeJSON(%v) = %q, %v; want %q", in, out, err, want)
+		}
+	}
+	if _, err := EncodeJSON(math.NaN()); err == nil {
+		t.Error("NaN must not encode")
+	}
+}
+
+func TestSetKeepsPositionAndDeleteRemoves(t *testing.T) {
+	o := NewObject()
+	o.Set("a", 1.0)
+	o.Set("b", 2.0)
+	o.Set("a", 3.0)
+	o.Delete("missing")
+	if k := o.Keys(); k[0] != "a" || k[1] != "b" || o.Len() != 2 {
+		t.Fatalf("keys = %v", k)
+	}
+	o.Delete("a")
+	if k := o.Keys(); len(k) != 1 || k[0] != "b" {
+		t.Fatalf("keys after delete = %v", k)
+	}
+}
+
+func TestFromGoRejectsWhatJSONCannotCarry(t *testing.T) {
+	cyc := map[string]any{}
+	cyc["self"] = cyc
+	for name, v := range map[string]any{"cycle": cyc, "nan": map[string]any{"n": math.NaN()}, "inf": math.Inf(1), "func": func() {}, "chan": make(chan int)} {
+		if _, err := FromGo(v); err == nil {
+			t.Errorf("%s: want an error", name)
+		}
+	}
+	tree, err := FromGo(map[string]any{"b": 1, "a": []int{1, 2}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if k := tree.(*Object).Keys(); k[0] != "a" || k[1] != "b" {
+		t.Fatalf("a Go map has no order, so keys are sorted: %v", k)
+	}
+}
+
+func TestParseJSONRejectsTrailingData(t *testing.T) {
+	if _, err := ParseJSON([]byte(`{"a":1} x`)); err == nil {
+		t.Fatal("trailing data must fail")
+	}
+	if _, err := ParseJSON([]byte(`{"a":`)); err == nil {
+		t.Fatal("truncated input must fail")
+	}
+}
+
+func TestCloneIsDeep(t *testing.T) {
+	v, _ := ParseJSON([]byte(`{"a":{"b":[1,{"c":2}]}}`))
+	c := v.(*Object).Clone()
+	inner, _ := c.Get("a")
+	inner.(*Object).Set("b", "changed")
+	orig, _ := v.(*Object).Get("a")
+	if b, _ := orig.(*Object).Get("b"); b == "changed" {
+		t.Fatal("clone shares structure with the original")
+	}
+}

package/ownmodel_test.go

@@ -0,0 +1,79 @@
+package pitypesafe
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/MichaelKinsy/pigpen/components/typesafe/libraries/typesafe"
+)
+
+type evalFunc func(ctx context.Context, req typesafe.SystemOneRequest) (*typesafe.SystemOneResult, error)
+
+func (f evalFunc) SystemOne(ctx context.Context, req typesafe.SystemOneRequest, _ *typesafe.RequestOptions) (*typesafe.SystemOneResult, error) {
+	return f(ctx, req)
+}
+
+func TestOwnModelClientNeedsAnEvaluatorAndUsesNoKeyOrHost(t *testing.T) {
+	isolate(t)
+	if _, err := New(Options{Backend: "ownmodel"}); !hasCode(err, CodeConfiguration) || !strings.Contains(err.Error(), "Evaluator") {
+		t.Fatalf("err = %v", err)
+	}
+	c, err := New(Options{Backend: "ownmodel", Ledger: OpenUsageLedger(LedgerOptions{Path: t.TempDir() + "/u.json"}), Evaluator: evalFunc(func(_ context.Context, req typesafe.SystemOneRequest) (*typesafe.SystemOneResult, error) {
+		return &typesafe.SystemOneResult{Model: "m", Answers: map[string]typesafe.Answer{"yes": typesafe.NoulAnswer{Noul: 0.4}}, Usage: typesafe.Usage{InputTokens: 3}}, nil
+	})})
+	if err != nil {
+		t.Fatal(err)
+	}
+	ev, err := c.Evaluate(context.Background(), sampleRequest())
+	if err != nil || ev.Model != "m" || c.GetUsage().InputTokens != 3 {
+		t.Fatalf("ev=%v err=%v", ev, err)
+	}
+	// No key is involved, so nothing is written to the auth state.
+	if s := mustAuth(t, nil); s.Verified {
+		t.Error("an own-model success must not verify a TypeSafe key")
+	}
+	if _, err := c.ListModels(context.Background()); !hasCode(err, CodeConfiguration) {
+		t.Errorf("list models: %v", err)
+	}
+}
+
+func TestOwnModelTimeoutAndErrorsAreClassified(t *testing.T) {
+	isolate(t)
+	slow := evalFunc(func(ctx context.Context, _ typesafe.SystemOneRequest) (*typesafe.SystemOneResult, error) {
+		<-ctx.Done()
+		return nil, ctx.Err()
+	})
+	c, _ := New(Options{Backend: "ownmodel", Timeout: 10 * time.Millisecond, Evaluator: slow, Ledger: OpenUsageLedger(LedgerOptions{Path: t.TempDir() + "/u.json"})})
+	if _, err := c.Evaluate(context.Background(), sampleRequest()); !hasCode(err, CodeTimeout) || !strings.Contains(err.Error(), "The configured model") {
+		t.Fatalf("timeout: %v", err)
+	}
+	c2, _ := New(Options{Backend: "ownmodel", Evaluator: evalFunc(func(context.Context, typesafe.SystemOneRequest) (*typesafe.SystemOneResult, error) {
+		return nil, errors.New("provider body with sk-secret")
+	}), Ledger: OpenUsageLedger(LedgerOptions{Path: t.TempDir() + "/u.json"})})
+	_, err := c2.Evaluate(context.Background(), sampleRequest())
+	if !hasCode(err, CodeResponse) || strings.Contains(err.Error(), "sk-secret") {
+		t.Fatalf("plain error: %v", err)
+	}
+}
+
+func TestEvaluationJSONKeepsQuestionOrderAndAddsElapsed(t *testing.T) {
+	ev := &Evaluation{
+		SystemOneResult: &typesafe.SystemOneResult{Model: "m", Answers: map[string]typesafe.Answer{"b": typesafe.NoulAnswer{Noul: 0.5}, "a": typesafe.NoulAnswer{Noul: 0.25}}, Usage: typesafe.Usage{InputTokens: 2}},
+		ElapsedMs:       7, Order: []string{"b", "a"},
+	}
+	out, err := ev.MarshalJSON()
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(out)
+	if !(strings.Index(s, `"b"`) < strings.Index(s, `"a"`)) || !strings.HasSuffix(s, `"elapsedMs":7}`) || strings.Index(s, `"model"`) > strings.Index(s, `"answers"`) {
+		t.Fatalf("json = %s", s)
+	}
+	d, _ := ev.DetailsJSON()
+	if !strings.Contains(string(d), `"order":["b","a"]`) {
+		t.Fatalf("details = %s", d)
+	}
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@pi-in-go/pigpen-pi-typesafe-api",
+  "version": "0.1.0",
+  "description": "Typed Go API for extension authors, a port of pi-typesafe's library half: one admission rule, request and spend caps, key store and auth state, judgment backends (TypeSafe, OpenRouter, Command Code, custom endpoint, own model), Ask, batching, calibration. Libraries only, no extension of its own.",
+  "keywords": [
+    "pig-package",
+    "typesafe",
+    "jev",
+    "library",
+    "pigpen"
+  ],
+  "license": "MIT",
+  "author": "Michael Kinsy",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MichaelKinsy/pigpen.git",
+    "directory": "components/pi-typesafe-api"
+  },
+  "homepage": "https://github.com/MichaelKinsy/pigpen/tree/main/components/pi-typesafe-api#readme",
+  "bugs": {
+    "url": "https://github.com/MichaelKinsy/pigpen/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "*.go",
+    "hostmodel",
+    "ui",
+    "testdata",
+    "evaluation_schema.json",
+    "go.mod",
+    "port",
+    "README.md",
+    "LICENSE",
+    "CREDITS.md",
+    "provenance.json",
+    "go.sum"
+  ]
+}

package/port/PORT.md

@@ -0,0 +1,6 @@
+# Port record: pi-typesafe-api
+
+The library half of the pi-typesafe port. The unmodified original (pinned commit `ed439f834665ad6fc652787f5ba7c23852566d49`,
+MIT, Ryan Gapac) and the complete record (file mapping, twins, scenarios, mutation results, deliberate differences) live in
+[`components/pi-typesafe/port/`](../../pi-typesafe/port/PORT.md); the original is vendored there once, not twice. This Package's
+Go twins of the library test files (`*_test.go` next to the code) are counted in that record.

package/provenance.json

@@ -0,0 +1,18 @@
+{
+  "origin": "ported",
+  "authors": ["Michael Kinsy"],
+  "license": "MIT",
+  "licenseFile": "LICENSE",
+  "upstreams": [
+    {
+      "name": "pi-typesafe",
+      "authors": ["Ryan Gapac"],
+      "url": "https://github.com/DevMortimer/pi-typesafe",
+      "revision": "ed439f834665ad6fc652787f5ba7c23852566d49",
+      "path": "port/PORT.md",
+      "license": "MIT",
+      "licenseFile": "LICENSE",
+      "attributionFile": "CREDITS.md"
+    }
+  ]
+}

package/review_test.go

@@ -0,0 +1,23 @@
+package pitypesafe
+
+import "testing"
+
+// Cases added by the review (rev-pigpen-typesafe).
+
+// Plain http: is allowed only for a loopback address. The original's WHATWG URL parser rejects a dotted
+// address with an octet above 255 (new URL throws), so 127.999.0.1 never passes its 127.0.0.0/8 rule; Go's
+// url.Parse accepts it as a host name, which the resolver would then look up in DNS and reach over plain
+// http: with the endpoint's key.
+func TestLoopbackHTTPNeedsARealLoopbackAddress(t *testing.T) {
+	for _, host := range []string{"http://127.999.0.1", "http://127.0.0.256:8080"} {
+		_, err := ResolveBackend(map[string]any{"label": "Local", "host": host, "keyEnv": "GATEWAY_JEV_KEY"})
+		if !hasCode(err, CodeConfiguration) || err.Error() != hostMessage {
+			t.Errorf("%s: %v", host, err)
+		}
+	}
+	for _, host := range []string{"http://127.0.0.1:8787", "http://127.255.255.254", "http://localhost:1", "http://[::1]:9"} {
+		if _, err := ResolveBackend(map[string]any{"label": "Local", "host": host, "keyEnv": "GATEWAY_JEV_KEY"}); err != nil {
+			t.Errorf("%s: %v", host, err)
+		}
+	}
+}