ai

type Answer ¶

type Answer struct {
	Type          QuestionType  `json:"type"`
	Name          string        `json:"name"`
	Probability   *float64      `json:"probability,omitempty"`
	Choice        string        `json:"choice,omitempty"`
	Score         *float64      `json:"score,omitempty"`
	Probabilities []Probability `json:"probabilities,omitempty"`
	Confidence    *float64      `json:"confidence,omitempty"`
}

Answer is a validated answer, in the Decisions API's shape: Type is the question's, or Refusal with nothing else set. A predicate sets Probability; a choice sets Choice; a score sets Score in [0, len(Levels)-1]. Choices and scores may add Probabilities and Confidence when the judge gives them.

type ChoiceOption ¶ added in v0.3.0

type ChoiceOption struct {
	Value       string `json:"value"`
	Description string `json:"description,omitempty"`
}

ChoiceOption is one value a choice question may answer.

type Code ¶

type Code string

const (
	CodeCanceled     Code = "canceled"
	CodeUnauthorized Code = "unauthorized"
	CodeRateLimited  Code = "rate_limited"
	CodeUnavailable  Code = "unavailable"
	CodeBadResponse  Code = "bad_response"
	CodeInternal     Code = "internal"
	// CodeStale: the model service changed or was removed since the model was
	// resolved, or while the run was in flight.
	CodeStale Code = "stale"
	// CodeIncomplete: the service ended the reply abnormally (cut off at the
	// output limit, filtered, failed part-way); nothing of it is kept.
	CodeIncomplete Code = "incomplete"
)

type Decision ¶

type Decision string

Decision is a permission gate's verdict on one tool call.

const (
	Allow   Decision = "allow"
	Approve Decision = "approve"
	Deny    Decision = "deny"
)

type Engine ¶

type Engine struct {

	// Current, if set, returns the service's stored version (an error when it
	// is gone). A run whose model has another version fails with CodeStale.
	// Set it before the first Run; it is called holding the engine's lock.
	Current func(ctx context.Context, serviceID int64) (int64, error)
	// contains filtered or unexported fields
}

Engine runs models through Genkit: one Genkit instance per model service configuration, created on first use. Genkit types never leave this package.

func NewEngine(l *slog.Logger, secrets func() []string) (*Engine, error)

func (e *Engine) Close()

func (e *Engine) Forget(serviceID int64)

func (e *Engine) Run(ctx context.Context, req Request) (<-chan Event, func() Result)

type Error ¶

type Error struct {
	Code   Code
	Msg    string
	Detail string
}

Error is a run failure. Msg never holds a key or a request or response body.

func (e *Error) Error() string

func (e *Error) Is(target error) bool

type Event ¶

type Event struct {
	Kind       string
	Text       string
	Call       *ToolCall
	Result     *ToolResult
	Interrupts []ToolCall
	Err        *Error
	Model      string // context only: the "slug/model" the run uses
}

Event kinds: text, tool_call, tool_result, interrupted (every call of the round awaiting approval, in call order), done, error. Exactly one of the last three ends the stream.

type Generator ¶

type Generator func(ctx context.Context, system, prompt string) (string, error)

Generator is one plain text generation: no tools, one turn.

type HTTPError ¶

type HTTPError struct{ Status int }

HTTPError is a judge HTTP failure; it never carries the body.

func (e *HTTPError) Error() string

type Judge ¶

type Judge interface {
	Ask(ctx context.Context, input string, qs []Question) ([]Answer, error)
}

Judge answers typed questions about input, which is untrusted data.

func NewGenJudge(gen Generator) Judge

func NewJudge(c *http.Client, format JudgeFormat, base, key, model string) (Judge, error)

type JudgeFormat ¶

type JudgeFormat string

JudgeFormat is a judge wire format.

const (
	FormatDecisions JudgeFormat = "decisions" // OpenAI Decisions API
	FormatSystemOne JudgeFormat = "systemone" // TypeSafe System One
)

func (f JudgeFormat) Models() []string

func (f JudgeFormat) Path() string

type Level ¶ added in v0.3.0

type Level struct {
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
}

Level is one level of a score question.

type Message ¶

type Message struct {
	Role    string // user, model or tool
	Text    string
	Calls   []ToolCall
	Results []ToolResult
}

Message is a conversation message for display; it is never used to resume.

func Messages(state []byte) ([]Message, error)

type Model ¶ added in v1.1.0

type Model struct{ ID, Name string }

Model is a listed model: its ID and, when the service gives one, a display name.

func ListModelsNamed(ctx context.Context, c *http.Client, kind, baseURL, apiKey string) ([]Model, error)

type ModelRef ¶

type ModelRef struct{ Service, Model string }

ModelRef names a model as "service/model"; the first "/" ends the service name.

func ParseModelRef(s string) (ModelRef, error)

type NoListError ¶

type NoListError struct{ Status int }

NoListError is ErrNoModelList with the status that said so.

func (e *NoListError) Error() string

func (e *NoListError) Is(target error) bool

type Probability ¶ added in v0.3.0

type Probability struct {
	Value       any     `json:"value"`
	Label       string  `json:"label,omitempty"`
	Probability float64 `json:"probability"`
}

Probability is the probability of one choice value (Value a string) or one score level (Value its index, Label its label).

type Question ¶

type Question struct {
	Name         string         `json:"name"`
	Type         QuestionType   `json:"type"`
	Instructions string         `json:"instructions"`
	Choices      []ChoiceOption `json:"choices,omitempty"` // choice: 2–255 unique values
	Levels       []Level        `json:"levels,omitempty"`  // score: 2–10, lowest first
}

Question is one typed question. Instructions come from the caller, never from mail; mail goes into the input.

type QuestionType ¶ added in v0.3.0

type QuestionType string

QuestionType is a question's type. Questions and answers take the OpenAI Decisions API's shape and names; the other formats convert to it.

const (
	Predicate QuestionType = "predicate" // the probability that it holds
	Choice    QuestionType = "choice"    // one value of Question.Choices
	Score     QuestionType = "score"     // a 0-based, possibly fractional, index into Question.Levels
	// Refusal is the type of an answer the judge declined to give.
	Refusal QuestionType = "refusal"
)

type Request ¶

type Request struct {
	Model  ResolvedModel
	System string
	State  []byte
	Prompt string
	// Context goes to the model before Prompt, in the same user turn, and
	// stays in the state; Messages never show it (quoted mail, for example).
	Context   string
	Tools     []ToolSpec
	Responses []ToolResult
	MaxTurns  int
}

Request is one run. State is the previous run's opaque state (empty = new conversation); Responses answer the calls that interrupted it.

type ResolvedModel ¶

type ResolvedModel struct {
	ServiceID, Version           int64
	Kind, BaseURL, Model, APIKey string
}

ResolvedModel is a model reference resolved against a stored service.

type Result ¶

type Result struct {
	State      []byte
	Messages   []Message
	Interrupts []ToolCall
	Err        *Error
}

type ToolCall ¶

type ToolCall struct {
	ID, Name string
	Args     json.RawMessage
}

type ToolResult ¶

type ToolResult struct {
	CallID, Name string
	Output       json.RawMessage
	Error        string
}

type ToolSpec ¶

type ToolSpec struct {
	Name, Description     string
	Schema                map[string]any
	Strict, NeedsApproval bool
	Gate                  func(ctx context.Context, args json.RawMessage) (Decision, error)
	Run                   func(ctx context.Context, args json.RawMessage) (any, error)
}

ToolSpec is a tool offered to the model for one Run. Gate, if set, decides each call first: Deny (or a Gate error) gives an error result, Approve interrupts, Allow goes on. A NeedsApproval tool's Run is never called: its calls interrupt the run instead.