systemone

type Client struct {
	// HTTP sends the requests.
	HTTP *http.Client
	// BaseURL is the origin the endpoint's paths are joined to.
	BaseURL string
	// APIKey is sent as a bearer token. A local server, such as Ollama,
	// takes none, and no authorization header is sent without one.
	APIKey string
	// Headers are sent on every request, after the authorization header.
	Headers  http.Header
	Endpoint *Endpoint
}

type Config struct {
	// StateJSON parses each text part of the state as JSON, so a prompt
	// template that renders a JSON document produces an object state
	// rather than a string one. A text that is not JSON is an error. A
	// fallback to another model takes that model's config, so set it there
	// too, or send the state as a data part, which needs no parsing.
	StateJSON bool `` /* 151-byte string literal not displayed */

	// Extra is merged into the top-level fields of the request body. It
	// reaches fields this package does not model, such as a gateway's
	// session_id or trace. It cannot name a field the request builds
	// itself: model, state, questions, images, audio, or videos.
	Extra map[string]any `` /* 177-byte string literal not displayed */
}

type Endpoint struct {
	// Name names the endpoint in errors.
	Name string
	// Path is the request path under the base URL.
	Path string
	// ModelsPath is the path of the model listing under the base URL,
	// empty when the endpoint has none.
	ModelsPath string
	// Route builds one model's request when it is not the native one. It
	// gets the model ID and the native body, which it may change, and
	// returns a suffix to the path, which is joined with a slash when it
	// does not start with one, and the body to send. It is per model
	// because one host can serve models on different routes, as Workers AI
	// does. When nil, the native body goes to Path with the model ID as
	// given.
	Route func(model string, body map[string]any) (suffix string, out any, err error)
	// Unwrap extracts the native response from the endpoint's envelope.
	// When nil, the response is the native body. An error it returns is
	// reported under Name, with its status kept, or as UNKNOWN when it has
	// none: the server answered with a success code, so neither the request
	// nor the server is known to be at fault.
	Unwrap func(body []byte) ([]byte, error)
}

type Info struct {
	Model    string                    `json:"model"`
	Provider string                    `json:"provider,omitempty"`
	ID       string                    `json:"id,omitempty"`
	Answers  map[string]map[string]any `json:"answers,omitempty"`
}

type Media struct {
	Images, Audio, Videos []string
}

type ModelInfo struct {
	ID          string `json:"id,omitempty"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	ReleaseDate string `json:"release_date,omitempty"`
}

type Option struct {
	Name        string
	Description any
}

type Options []Option

type Question struct {
	Type string `json:"type"`
	// Instructions is the question's text, or the structured value a
	// runtime question gives, after the preamble.
	Instructions any `json:"instructions"`
	// Criteria is the options and their descriptions for a choice question,
	// in order; a map of side to description for a noul question; and an
	// ordered list of level descriptions for a score question. A
	// description is a string, or the guidance that replaces it on the wire.
	Criteria any `json:"criteria,omitempty"`

	// Labels are a score question's level strings, which the legend is
	// built from whatever form the levels take on the wire.
	Labels []string `json:"-"`
}

type Reads struct {
	Images, Audio, Video bool
}

type Request struct {
	State any
	// Media is sent in the images, audio, and videos fields, which the
	// servers place before the state. Each field is sent only when it has
	// media, since a server that does not read a kind can refuse its field.
	Media     Media
	Questions map[string]Question
	// Extra is merged into the top-level fields, which is the escape hatch
	// to a field this package does not model. It cannot replace a field
	// the request builds itself: model, state, questions, images, audio, or
	// videos.
	Extra map[string]any
}

type Response struct {
	Info
	Usage struct {
		InputTokens  int      `json:"input_tokens"`
		OutputTokens int      `json:"output_tokens"`
		Cost         *float64 `json:"cost,omitempty"`
	} `json:"usage"`
}

type Spec struct {
	// Label names the model in the Dev UI.
	Label string
	// Reads is the media requests may carry. A kind the model does not
	// read is refused before a request is sent.
	Reads Reads
}