TypeSafe SDK for Go v0.7.0
Go SDK · Python v0.7.0 parity

Typed answers to named questions.

Ask yes/no, classification, and rubric questions about any state in one request. Get statically typed answers back, then decide in plain Go.

Browse examples API reference
$ go get github.com/captain-corgi/typesafe-sdk-go
0dependencies
3typed primitives
91examples
main.go
resp, err := client.SystemOne(ctx, &typesafe.SystemOneParams{
    State: "I was charged twice. Please fix it today!",
    Questions: typesafe.Questions{
        "topic": typesafe.Choice{
            Instructions: "What is this about?",
            Criteria: typesafe.ChoiceCriteria{
                "billing":   "Charges or invoices",
                "technical": "Something is broken",
            },
        },
        "urgent": typesafe.Noul{Instructions: "Is this urgent?"},
        "anger": typesafe.Score{
            Instructions: "How upset is the customer?",
            Criteria:     typesafe.ScoreCriteria{"calm", "annoyed", "upset"},
        },
    },
})

topic := resp.Choices()["topic"] // .Choice "billing", .Confidence 0.97
urgent := resp.Nouls()["urgent"] // .Noul 0.91
anger := resp.Scores()["anger"]  // .Score 1.4
Introduction

The SDK in eight slides

Use the arrow keys or swipe to move between slides. Press F for full screen.

Open in new tab
Why this SDK

Small surface. Production defaults.

Idiomatic Go on top of the standard library, with the same wire protocol, errors, and retry semantics as the Python SDK.

Typed answers

The question kind fixes the answer type. Noul, Choice, and Score map to their own answer structs.

Zero dependencies

Only net/http, encoding/json, and log/slog. CI proves the module has no third-party requirements.

Smart retries

Exponential backoff with jitter, Retry-After support, a per-call budget, and custom retry selectors.

Structured errors

Match any failure with errors.As: *RateLimitError, *TimeoutError, *ResponseValidationError, and more.

Safe for concurrency

One Client per process, shared across goroutines. Verified with -race in CI.

Secure and in parity

HTTPS only, secret headers redacted from logs, bounded response size. Feature parity with Python SDK v0.7.0.

How it works

Three primitives. One call. Your policy in Go.

Describe the state, ask named questions, and branch on typed answers. The SDK validates, sends, retries, and decodes.

Noul

Yes or no, as a probability

NoulAnswer.Noul is a float from 0 to 1. Compare it to a threshold you measured.

Choice

Pick one label

ChoiceAnswer has the Choice, its Confidence, and every label's probability.

Score

Place on an ordered rubric

ScoreAnswer.Score is a position on your rubric, with a legend and probabilities.

Raw

Pass anything through

RawQuestion sends a question shape untouched, for fields this SDK version does not model.

Quick start

Up and running in a minute

Set your key, create one client, and ask your first question.

  • The client reads TYPESAFE_API_KEY from the environment.
  • Questions are validated before any network I/O.
  • Retries, timeouts, and headers are handled for you.
  • Responses include usage stats and raw HTTP access.
quickstart/main.go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/captain-corgi/typesafe-sdk-go"
)

func main() {
    client, err := typesafe.NewClient() // reads TYPESAFE_API_KEY
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    resp, err := client.SystemOne(context.Background(), &typesafe.SystemOneParams{
        State: "The export button crashes the app every time.",
        Questions: typesafe.Questions{
            "is_bug": typesafe.Noul{Instructions: "Is this a bug report?"},
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    if resp.Nouls()["is_bug"].Noul >= 0.8 {
        fmt.Println("route to engineering")
    }
}
Examples

91 runnable examples, each with a diagram

Every example is one package main that uses only the standard library and this SDK, and runs against the live API. Pick one to see its flow and full source.

Loading examples…

Thresholds in the examples illustrate control flow. Measure them on labeled data from your application before production use. Full index: examples/README.md.

Documentation

Deep dives

Getting started

Install, first call, choosing a question kind.

Architecture

Module map, life of a call, concurrency model.

Configuration

Options, environment variables, timeouts, HTTP client.

Questions

Noul, Choice, Score, Raw, and what goes on the wire.

Responses

Typed answers, usage stats, raw access, validation.

Errors

Error taxonomy, matching patterns, recipes.

Retries and timeouts

Backoff, jitter, budget, Retry-After, selectors.

Wire protocol

Methods, paths, headers, JSON encoding.

Observability

Logging, redaction, slog integration.