Home EN

TypeSafe AI Go SDK — Wiki

English | 简体中文

---

Official Go SDK for TypeSafe AI — calibrated, deterministic System One evaluation models that answer classification, scoring, verification, and bounding box localization questions about any text, structured JSON, or images.

Ask up to dozens of questions in a single call, and get back well-calibrated probabilities, categorical labels, rubric scores, and bounding boxes instead of free-form text you have to parse.

client, err := typesafe.NewClient(
    typesafe.WithImages(true), // enable multimodal & box localization support
)
if err != nil {
	log.Fatal(err)
}
defer client.Close()

response, err := client.SystemOne(ctx, state, typesafe.Questions{
	"billing": typesafe.NewNoul("Is this message about billing?"),
	"queue": typesafe.NewChoice(
		map[string]any{"billing": "Charges or invoices", "technical": "Bug reports", "other": nil},
		typesafe.WithInstructions("Which queue should handle this ticket?"),
	),
	"urgency": typesafe.NewScore(
		[]any{"routine", "elevated", "critical emergency"},
		typesafe.WithInstructions("How urgent is this?"),
	),
	"target": typesafe.NewBox("Locate the primary item in the image"),
}, typesafe.WithModel(typesafe.ModelJevPreview))

---

Guides

Page	Covers
Use Cases	What people build with it, with a worked triage example
Questions	The noul, choice, score, and box primitives, their options, and raw questions
Images & Multimodal Assets	Image constructors, asset collection, Danger Zone headers, and limits
Responses	Response accessors (Nouls(), Choices(), Scores(), Boxes()), nullable tokens, and decoding rules
Custom Response Models	Decoding straight into your own struct with generic SystemOneAs[T]
CLI	The typesafe command: install, flags (--box, --images), output formats, exit codes
Configuration	Client options, environment variables, gzip compression, Danger Zone, per-call options
Retry Policy	Retries, exponential backoff with jitter, Retry-After header respect, and the retry budget
Errors	The typed error taxonomy (HTTP 413, 415, 429, 529), helpers, and matching
Logging	Structured logging via log/slog and credential redaction
Security	Redaction, protected headers, redirects, bounded reads (16 MB body, 16 MiB image), TLS
Concurrency	Sharing one client safely across goroutines and bounding concurrency
Examples	Runnable programs in the repository

---

At a glance

Module	github.com/guchengod/typesafe-sdk-go
Requires	Go 1.26 or newer
Dependencies	None — standard library only (net/http, encoding/json, log/slog)
API key	TYPESAFE_API_KEY, or typesafe.WithAPIKey
Endpoints	POST /v1/systemone, GET /v1/models
Compression	Automatic gzip for request payloads $\ge 1\text{ KiB}$ (WithCompression(true))
Multimodal	PNG and JPEG formats, up to 16 MiB per image, 32 MiB total request limit
Reference	pkg.go.dev
Releases	Releases

---

Concepts in one minute

One call, SystemOne, evaluates a set of questions against a state:

• State — the content the questions refer to. Any JSON-encodable value: a string, a map, a struct, an array, or embedded *typesafe.Image assets. A ticket, a document, an evaluation candidate, or a record from your database.
• Assets — optional dictionary of image assets. When *typesafe.Image instances are placed in the state, the SDK automatically collects them via CollectAssets and references them in the JSON payload.
• Questions — a map of names you choose to questions. The names are how you read the answers back, so name them after the decision they support ("queue", "is_spam", "urgency", "cup_box").
• Answers — a response keyed by those names, one answer per question, whose type always matches the question's type. The response also reports the model that answered and token usage.