Client Options and Environment

Package: github.com/therealbill/typesafe-go (import path typesafe).

Client

type Client struct {
    // Has unexported fields.
}

Client calls the TypeSafe API. A single Client is safe for concurrent use by multiple goroutines. The zero value is not usable; NewClient builds one.

NewClient

func NewClient(opts ...Option) (*Client, error)

NewClient builds a Client. It fails when no API key is configured, returning ErrMissingAPIKey (documented on the errors and exit codes reference).

(*Client) Close

func (c *Client) Close() error

Close releases idle connections held by a client-owned http.Client.

(*Client) SystemOne

func (c *Client) SystemOne(ctx context.Context, state any, questions Questions, opts ...RequestOption) (*SystemOneResponse, error)

SystemOne asks the named questions about state and returns the typed answers. state is a string, map, slice, or struct that encodes to JSON. Questions and SystemOneResponse are documented on the question types and response types references.

(*Client) ListModels

func (c *Client) ListModels(ctx context.Context, opts ...RequestOption) (*ListModelsResponse, error)

ListModels returns the models available to the account. ListModelsResponse is documented on the response types reference.

(*Client) String

func (c *Client) String() string

String renders the client for fmt verbs. It returns typesafe.Client{base_url: <url>, model: <model>} and never includes the API key.

(*Client) LogValue

func (c *Client) LogValue() slog.Value

LogValue renders the client for slog. It returns slog.GroupValue(slog.String("base_url", ...), slog.String("model", ...)), only those two string attributes, never the API key.

Configuration resolution order

Defaults and environment variable names. Explicit options win over the environment, which wins over these defaults.

Defaults and environment variable constants

const (
    DefaultBaseURL = "https://api.typesafe.ai"
    DefaultModel   = "jev-latest"
    DefaultTimeout = 10 * time.Second

    EnvAPIKey       = "TYPESAFE_API_KEY"
    EnvBaseURL      = "TYPESAFE_BASE_URL"
    EnvDefaultModel = "TYPESAFE_DEFAULT_MODEL"
    EnvLogLevel     = "TYPESAFE_LOG_LEVEL"
)

Option

type Option func(*Client) error

Option configures a Client.

Client-level option functions

Base URL validation

normalizeBaseURL validates the value given to WithBaseURL and the value read from TYPESAFE_BASE_URL:

A path prefix in the base URL is preserved: requests are built with url.JoinPath, so WithBaseURL("https://gw.example.com/api") plus a request to /v1/systemone produces https://gw.example.com/api/v1/systemone.

RequestOption

type RequestOption func(*requestConfig) error

RequestOption configures a single call. An option that cannot be applied returns an error, which the call returns before contacting the API. Options are applied before Instrumentation.RequestStart is called, so an option error (for example from WithRequestTimeout) is returned before instrumentation starts and is never recorded by an Instrumentation hook; state and questions validation errors, which happen after RequestStart, are recorded.

Per-call option functions

NewLogger

func NewLogger(w io.Writer, level string) *slog.Logger

NewLogger returns a text logger on w at the named level: debug, info, warning (or warn), error. Any other value, including "off" and "", returns a logger that discards everything.

RetryPolicy

type RetryPolicy struct {
    MaxRetries      int
    InitialDelay    time.Duration
    MaxDelay        time.Duration
    Jitter          float64
    Budget          time.Duration
    RetryStatuses   []int
    RetryOnConnErr  bool
    RetryOnTimeout  bool
    HonorRetryAfter bool
    MaxRetryAfter   time.Duration
    ShouldRetry     func(resp *http.Response, err error) bool
}

RetryPolicy controls how failed requests are retried. DefaultRetryPolicy returns a populated policy whose fields can then be changed. A zero RetryPolicy disables retries.

DefaultRetryPolicy

func DefaultRetryPolicy() RetryPolicy

DefaultRetryPolicy returns the policy used when none is configured. It matches the official Python SDK’s defaults.

Instrumentation

type Instrumentation interface {
    // RequestStart is called once per SystemOne or ListModels call. The
    // returned context is used for every HTTP attempt. The returned function
    // is called exactly once when the call finishes.
    RequestStart(ctx context.Context, info RequestInfo) (context.Context, func(RequestResult))
    // Transport wraps the HTTP round tripper used by the client. It is called
    // once at client construction and may return rt unchanged.
    Transport(rt http.RoundTripper) http.RoundTripper
}

Instrumentation observes client calls. The otel subpackage provides an OpenTelemetry implementation; its span attribute keys are documented on the span attributes reference.

RequestInfo

type RequestInfo struct {
    Operation     string
    Model         string
    QuestionCount int
    NoulCount     int
    ChoiceCount   int
    ScoreCount    int
    State         any
    Questions     Questions
}

RequestInfo describes a call about to be made. It is passed to Instrumentation.RequestStart before the first HTTP attempt.

RequestResult

type RequestResult struct {
    Attempts  int
    Status    int
    RequestID string
    Model     string
    Usage     Usage
    Response  *SystemOneResponse
    Err       error
}

RequestResult describes how a call ended. It is passed to the function returned by Instrumentation.RequestStart exactly once.