jev

README

jev-go

A Go SDK for TypeSafe's Jev API.

Install

go get github.com/kyledickey/jev-go

The package name is jev.

Usage

The client reads your key from TYPESAFE_API_KEY by default.

client, err := jev.NewClient()
if err != nil {
	log.Fatal(err)
}

resp, err := client.SystemOne(ctx, jev.SystemOneRequest{
	State: "I bought this product 10 days ago and I want a full refund.",
	Questions: map[string]jev.Question{
		"eligible": jev.NoulQuestion{
			Instructions: "Is the customer eligible for a refund?",
			Criteria: &jev.NoulCriteria{
				True: "Full refunds are allowed within 30 days of purchase.",
			},
		},
	},
})
if err != nil {
	log.Fatal(err)
}

if a, ok := resp.Answers["eligible"].(*jev.NoulAnswer); ok {
	fmt.Printf("eligible: %.2f\n", a.Noul)
}

There are three question types, each with a matching answer type:

Question	Answer
NoulQuestion	*NoulAnswer
ChoiceQuestion	*ChoiceAnswer
ScoreQuestion	*ScoreAnswer

See the Jev docs for how each one works, and examples/basic for a full program.

Options

client, err := jev.NewClient(
	jev.WithAPIKey("..."),
	jev.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
	jev.WithBaseURL("https://api.typesafe.ai/v1"),
)

Errors

Non-2xx responses come back as *jev.APIError, which has the status code, headers, and raw body.

var apiErr *jev.APIError
if errors.As(err, &apiErr) {
	log.Printf("status %d: %s", apiErr.StatusCode, apiErr.Body)
}

Requests aren't retried, so wrap calls yourself if you need that.

Contributing

Issues and PRs are welcome. For anything bigger than a small fix, it's worth opening an issue first so we can talk it through.

Before sending a PR, make sure these pass (CI runs the same checks):

gofmt -l .
go vet ./...
go test -race ./...

License

MIT

Documentation

Overview

Package jev provides a Go SDK for TypeSafe's Jev API.

Index

• Constants
• Variables
• type APIError
  • func (e *APIError) Error() string
  • func (e *APIError) Unwrap() error
• type Answer
• type ChoiceAnswer
• type ChoiceQuestion
  • func (q ChoiceQuestion) MarshalJSON() ([]byte, error)
• type Client
  • func NewClient(opts ...Option) (*Client, error)
  • func (c *Client) SystemOne(ctx context.Context, req SystemOneRequest) (*SystemOneResponse, error)
• type NoulAnswer
• type NoulCriteria
• type NoulQuestion
  • func (q NoulQuestion) MarshalJSON() ([]byte, error)
• type Option
  • func WithAPIKey(key string) Option
  • func WithBaseURL(baseURL string) Option
  • func WithHTTPClient(client *http.Client) Option
• type Question
• type ScoreAnswer
• type ScoreQuestion
  • func (q ScoreQuestion) MarshalJSON() ([]byte, error)
• type SystemOneRequest
  • func (r SystemOneRequest) MarshalJSON() ([]byte, error)
• type SystemOneResponse
  • func (r *SystemOneResponse) UnmarshalJSON(data []byte) error
• type Usage

Constants

const DefaultModel = "jev-latest"

DefaultModel is used when a request does not specify a model.

Variables

var (
	ErrNilClientOpts  = errors.New("jev: client option must not be nil")
	ErrAPIKeyMissing  = errors.New("jev: API key is required; set TYPESAFE_API_KEY or use WithAPIKey")
	ErrNilHTTPClient  = errors.New("jev: HTTP client must not be nil")
	ErrInvalidBaseURL = errors.New("jev: invalid base URL")
)

Types

type APIError

type APIError struct {
	StatusCode int
	Header     http.Header
	Body       []byte
	// contains filtered or unexported fields
}

APIError represents a non-successful HTTP reponse from the API.

func (*APIError) Error

func (e *APIError) Error() string

Error returns a short description of the error.

func (*APIError) Unwrap

func (e *APIError) Unwrap() error

type Answer

type Answer interface {
	// contains filtered or unexported methods
}

Answer represents one of the supported evaluation results.

type ChoiceAnswer

type ChoiceAnswer struct {
	Choice        string             `json:"choice"` // The key of the selected option
	Probabilities map[string]float64 `json:"probabilities"`
	Confidence    float64            `json:"confidence"`
}

Choice answer contains a selected option and its distribution.

see https://docs.typesafe.ai/primitives/choice

type ChoiceQuestion

type ChoiceQuestion struct {
	Instructions any
	Criteria     map[string]any
}

ChoiceQuestion asks the model to select one named option.

see https://docs.typesafe.ai/primitives/choice

func (ChoiceQuestion) MarshalJSON

func (q ChoiceQuestion) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client holds all the configuration for API requests

func NewClient

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

NewClient constructs a Jev client from defaults and provided options.

Reads TYPESAFE_API_KEY unless WithAPIKey is provided.

func (*Client) SystemOne

func (c *Client) SystemOne(ctx context.Context, req SystemOneRequest) (*SystemOneResponse, error)

SystemOne calls the API to evaluate the set of questions. Performs one attempt, no retry loop.

type NoulAnswer

type NoulAnswer struct {
	Noul float64 `json:"noul"` // 0-1
}

NoulAnswer contains the probability that a statement is true.

see https://docs.typesafe.ai/primitives/noul

type NoulCriteria

type NoulCriteria struct {
	True  any `json:"true,omitempty"`
	False any `json:"false,omitempty"`
}

NoulCriteria provides descriptions for the two possible outcomes.

type NoulQuestion

type NoulQuestion struct {
	Instructions any
	Criteria     *NoulCriteria
}

NoulQuestion asks for the probability that a statement is true.

see https://docs.typesafe.ai/primitives/noul

func (NoulQuestion) MarshalJSON

func (q NoulQuestion) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler

type Option

type Option func(*clientConfig)

Option configures a client during NewClient

func WithAPIKey

func WithAPIKey(key string) Option

WithAPIKey overrides the API key read from TYPESAFE_API_KEY.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the API base URL.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient replaces the default HTTP Client.

type Question

type Question interface {
	json.Marshaler
	// contains filtered or unexported methods
}

Question represents a question that can be included in an evaluation.

type ScoreAnswer

type ScoreAnswer struct {
	Score         float64            `json:"score"`
	Legend        map[string]string  `json:"legend"`
	Probabilities map[string]float64 `json:"probabilities"`
	Confidence    float64            `json:"confidence"`
}

ScoreAnswer contains a numeric score.

see https://docs.typesafe.ai/primitives/score

type ScoreQuestion

type ScoreQuestion struct {
	Instructions any
	Criteria     []any
}

ScoreQuestion asks the model to evaluate the state against ordered levels.

see https://docs.typesafe.ai/primitives/score

func (ScoreQuestion) MarshalJSON

func (q ScoreQuestion) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

type SystemOneRequest

type SystemOneRequest struct {
	Model     string              `json:"model"` // Defaults to jev-latest
	State     any                 `json:"state"` // The content evaluated by the questions
	Questions map[string]Question `json:"questions"`
}

SystemOneRequest contains the input for one evaluation.

func (SystemOneRequest) MarshalJSON

func (r SystemOneRequest) MarshalJSON() ([]byte, error)

MarshalJSON encodes an evaluation request.

type SystemOneResponse

type SystemOneResponse struct {
	Model   string            `json:"model"`
	Answers map[string]Answer `json:"answers"`
	Usage   Usage             `json:"usage"`
}

SystemOneResponse contains an evaluation's results and metadata.

func (*SystemOneResponse) UnmarshalJSON

func (r *SystemOneResponse) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes an evaluation response.

type Usage

type Usage struct {
	InputTokens  int64 `json:"input_tokens"`
	OutputTokens int64 `json:"output_tokens"`
}

Usage reports the token counts returned by the service.