assistant

type Batch struct {
	Calls []ToolCall `json:"calls"`
	// Results are the answers so far, in the calls' order: Results[i]
	// answers Calls[i]; the first call without one is the one waiting.
	Results []Part `json:"results"`
}

type Decision string

type Invalid struct {
	Field string
	Min   int
	Max   int
}

type Kind string

type Limiter struct {

	// Now is the clock (time.Now when nil).
	Now func() time.Time
	// contains filtered or unexported fields
}

type Loop struct {
	Provider Provider
	Model    string
	System   string
	Tools    Toolbox
	// MaxRounds is how many batches of tool calls one run may answer and go
	// back to the model with.
	MaxRounds int
	// MaxOutputTokens is one reply's limit; Budget the whole run's, input and
	// output of every call together.
	MaxOutputTokens int
	Budget          int
	// OnText receives the reply's text as it streams (nil: dropped).
	OnText func(string)
	// OnMessage receives every message the run appends, as it appends it -
	// before the toolbox runs that message's calls (nil: none).
	OnMessage func(Message)
}

type Message struct {
	Role  Role   `json:"role"`
	Parts []Part `json:"parts"`
}

type Part struct {
	Kind     PartKind        `json:"kind"`
	Text     string          `json:"text,omitempty"`
	CallID   string          `json:"call_id,omitempty"`
	Tool     string          `json:"tool,omitempty"`
	Args     json.RawMessage `json:"args,omitempty"`
	IsError  bool            `json:"is_error,omitempty"`
	Provider string          `json:"provider,omitempty"`
	Raw      json.RawMessage `json:"raw,omitempty"`
	// Context marks a text part the server wrote into the person's message:
	// what they had selected (its paths in Args). Sent to the model like any
	// text; the panel shows it as the selection, not as their words.
	Context bool `json:"context,omitempty"`
}

type PartKind string

type Provider interface {
	// Kind is the provider's name: KindOpenAI, KindAnthropic, KindOllama.
	Kind() Kind
	// Chat sends req and streams the reply: onText is called with every
	// piece of text as it arrives (from this goroutine; never nil-checked by
	// the caller - pass a no-op).
	Chat(ctx context.Context, req Request, onText func(string)) (*Turn, error)
	// Models lists the models the address offers, for the settings page.
	Models(ctx context.Context) ([]string, error)
}

type ProviderError struct {
	Provider Kind
	// Status is the HTTP status the provider answered; 0 when it never
	// answered (the address did not answer, the stream broke).
	Status int
	// Message is the provider's own words (English, as it sent them).
	Message string
}

type Request struct {
	Model     string
	System    string
	Messages  []Message
	Tools     []ToolDef
	MaxTokens int
}

type Result struct {
	// Added are the messages the run appended to the conversation: the
	// model's turns and the tool answers, in order.
	Added []Message
	// Pending is the batch that waits for the person (Reason "pending").
	Pending *Batch
	Reason  string
	Usage   Usage
	// Model is the model that answered last.
	Model string
	// RefusalCategory is the provider's reason for a refusal, when it gave
	// one.
	RefusalCategory string
}

type Role string

type Settings struct {
	// Enabled turns the assistant on. Off by default: nothing leaves the
	// server for a model until an administrator says so.
	Enabled bool `json:"enabled"`
	// HideButton keeps the assistant's button out of the explorer's toolbar
	// for everybody, whatever else is set - the switch for an installation
	// that wants no trace of it.
	HideButton bool   `json:"hide_button"`
	Provider   Kind   `json:"provider"`
	BaseURL    string `json:"base_url"`
	Model      string `json:"model"`
	// MaxToolRounds is how many times one request may go back to the model
	// with tool answers before it is stopped.
	MaxToolRounds int `json:"max_tool_rounds"`
	// MaxOutputTokens is the longest single reply the model may write.
	MaxOutputTokens int `json:"max_output_tokens"`
	// MaxRequestTokens is one request's budget: input and output of every
	// round together. Reaching it stops the request.
	MaxRequestTokens int `json:"max_request_tokens"`
	// TimeoutSeconds is how long one call to the provider may take, retries
	// included.
	TimeoutSeconds int `json:"timeout_seconds"`
	// RequestsPerMinute is how many requests one person may start a minute.
	RequestsPerMinute int `json:"requests_per_minute"`
	// RetentionDays is how long a conversation is kept after it was last
	// used.
	RetentionDays int `json:"retention_days"`
}

type Stop string

type ToolCall struct {
	ID       string          `json:"id"`
	Name     string          `json:"name"`
	Args     json.RawMessage `json:"args"`
	Decision Decision        `json:"decision,omitempty"`
}

type ToolDef struct {
	Name        string
	Description string
	Schema      json.RawMessage
}

type ToolOutcome struct {
	// Text is what the model is told: the tool's answer, or why it did not
	// run.
	Text    string
	IsError bool
	// Pending: the call waits for the person (it cannot be undone and they
	// have not answered). The loop stops here; Text is not used.
	Pending bool
}

type Toolbox interface {
	// Defs are the tools the model is offered - the same list, in the same
	// order, for every call of a conversation (a provider ties what it
	// cached, and Anthropic its thinking blocks, to the tools).
	Defs() []ToolDef
	// Run runs one call (or decides it must wait for the person).
	Run(ctx context.Context, call ToolCall) ToolOutcome
}

type Turn struct {
	// Parts is the model's message: text, tool calls and the blocks its
	// provider wants back (PartOpaque), in the order they came.
	Parts []Part
	Stop  Stop
	Usage Usage
	// Model is the model that answered (a provider may name the exact
	// version, or the model it fell back to).
	Model string
	// RefusalCategory is the provider's word for why it declined, when it
	// said one.
	RefusalCategory string
}

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