genai

type Answer struct {
	// Type is the type of the question this is the answer to.
	Type QuestionType `json:"type"`
	// Noul is the probability that the answer is yes, from 0 to 1. It is set for QuestionNoul.
	Noul float64 `json:"noul,omitzero"`
	// Choice is the highest probability option. It is set for QuestionChoice.
	Choice string `json:"choice,omitzero"`
	// Score is the probability weighted value across the levels. It can land between levels. It is set for
	// QuestionScore.
	Score float64 `json:"score,omitzero"`
	// Confidence is how certain the model is, derived from Probabilities. It is set for QuestionChoice and
	// QuestionScore.
	Confidence float64 `json:"confidence,omitzero"`
	// Probabilities maps each option, or each level as a string key, to its probability. It is set for
	// QuestionChoice and QuestionScore.
	Probabilities map[string]float64 `json:"probabilities,omitzero"`
	// Legend maps each level as a string key to the description passed in Question.Score for that level.
	// It is set for QuestionScore.
	Legend ScoreLegend `json:"legend,omitzero"`
	// contains filtered or unexported fields
}

type Answers map[string]*Answer

type Array []any

type AudioFormat struct {
	SampleRate int
}

type CacheEntry interface {
	GetID() string
	GetDisplayName() string
	GetExpiry() time.Time
}

type Citation struct {
	// CitedText is the text that was cited.
	CitedText string `json:"cited_text,omitzero"`
	// StartIndex is the starting character position of the citation in the answer (0-based).
	StartIndex int64 `json:"start_index,omitzero"`
	// EndIndex is the ending character position of the citation in the answer (0-based, exclusive).
	EndIndex int64 `json:"end_index,omitzero"`

	// Sources contains information about the source documents or tools that support this citation.
	Sources []CitationSource `json:"sources,omitzero"`
	// contains filtered or unexported fields
}

type CitationSource struct {
	// Type indicates the source type.
	Type CitationType `json:"type,omitzero"`
	// ID is a unique identifier for the source (e.g., document ID, tool call ID).
	ID string `json:"id,omitzero"`
	// Title is the human-readable title of the source.
	Title string `json:"title,omitzero"`
	// URL is the web URL for the source, if applicable.
	URL string `json:"url,omitzero"`
	// Snippet is a snippet from the source, if applicable. It is the web search query for CitationWebQuery.
	Snippet string `json:"snippet,omitzero"`
	// StartCharIndex is the starting character position of the citation in the sourced document (0-based).
	StartCharIndex int64 `json:"start_index,omitzero"`
	// EndCharIndex is the ending character position of the citation in the sourced document (0-based, exclusive).
	EndCharIndex int64 `json:"end_index,omitzero"`
	// StartPageNumber is the starting page number of the citation in the sourced document (1-based).
	StartPageNumber int64 `json:"start_page_number,omitzero"`
	EndPageNumber   int64 `json:"end_page_number,omitzero"`
	// StartBlockIndex is the starting block index of the citation in the sourced document (0-based).
	StartBlockIndex int64 `json:"start_block_index,omitzero"`
	EndBlockIndex   int64 `json:"end_block_index,omitzero"`

	// Date is the date of the source, if applicable.
	Date string `json:"date,omitzero"`
	// Metadata contains additional source-specific information.
	// For document sources: document index, page numbers, etc.
	// For tool sources: tool output, function name, etc.
	// For web sources: encrypted index, search result info, etc.
	Metadata map[string]any `json:"metadata,omitzero"`
	// contains filtered or unexported fields
}

type CitationType int32

type DecisionContent interface {
	// Validate ensures the content is valid.
	Validate() error
	// contains filtered or unexported methods
}

type DecisionUsage struct {
	// InputTokens counts the prompt tokens evaluated for all questions.
	InputTokens int64 `json:"input_tokens"`
	// OutputTokens counts output tokens reported by the provider, often zero for decision models.
	OutputTokens int64 `json:"output_tokens"`
	// ReasoningTokens counts reasoning tokens within OutputTokens, when reported by the provider.
	ReasoningTokens int64 `json:"reasoning_tokens,omitzero"`
}

type Doc struct {
	// Filename is the name of the file. For many providers, only the extension
	// is relevant. They only use mime-type, which is derived from the filename's
	// extension. When an URL is provided or when the object provided to Document
	// implements a method with the signature `Name() string`, like an
	// `*os.File`, Filename is optional.
	Filename string `json:"filename,omitzero"`
	// Src is raw document data. It is perfectly fine to use a bytes.NewReader() or *os.File.
	Src io.ReadSeeker `json:"bytes,omitzero"`
	// URL is the reference to the raw data. When set, the mime-type is derived from the URL.
	URL string `json:"url,omitzero"`
	// contains filtered or unexported fields
}

type EffortLevel string

type EmbeddingRequest struct {
	// Inputs contains one text or document block per output vector.
	Inputs []Request `json:"inputs"`
	// Dimensions is the requested vector size, or zero for the model default.
	// Support depends on the provider and model.
	Dimensions int `json:"dimensions,omitzero"`
}

type EmbeddingResponse struct {
	Embeddings [][]float32 `json:"embeddings"`
	// Usage is zero when the provider doesn't report token counts.
	Usage Usage `json:"usage,omitzero"`
}

type FinishReason string

type GenOption interface {
	// Validate ensures the options object is valid.
	Validate() error
}

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

type GenOptionImage struct {
	Width  int
	Height int
	// contains filtered or unexported fields
}

type GenOptionPollInterval time.Duration

type GenOptionSeed int64

type GenOptionText struct {
	// Temperature adjust the creativity of the sampling. Generally between 0 and 2.
	Temperature float64
	// TopP adjusts correctness sampling between 0 and 1. The higher the more diverse the output.
	TopP float64
	// MaxTokens is the maximum number of tokens to generate. Used to limit it
	// lower than the default maximum, for budget reasons.
	MaxTokens int64
	// TopLogprobs requests to return the top logprobs in the reply.
	TopLogprobs int64
	// SystemPrompt is the prompt to use for the system role.
	SystemPrompt string

	// TopK adjusts sampling where only the N first candidates are considered.
	TopK int64
	// Stop is the list of tokens to stop generation.
	Stop []string

	// ReplyAsJSON enforces the output to be valid JSON, any JSON. It is
	// important to tell the model to reply in JSON in the prompt itself.
	ReplyAsJSON bool
	// DecodeAs enforces a reply with a specific JSON structure. It must be either a JSON object or array
	// that can be decoded by encoding/json and can have jsonschema tags, usually a pointer to a struct, or
	// a JSONSchema.
	//
	// Not every provider accepts an array at the root of the reply, e.g. OpenAI and Anthropic require an
	// object. Wrap the slice in a struct with a single field when the provider rejects it.
	//
	// It is important to request the model to "reply in JSON" in the prompt itself.
	//
	// If you use a JSONSchema, it will be used to validate the reply.
	//
	// If you use a pointer to a struct, it is recommended to use jsonschema_description tags to describe each
	// field or argument. Use jsonschema:"enum=..." to enforce a specific value within a set. Use omitempty to
	// make the field optional. See https://github.com/invopop/jsonschema#example for more examples.
	DecodeAs any
	// contains filtered or unexported fields
}

type GenOptionTools struct {
	// Tools is the list of tools that the LLM can request to call.
	Tools []ToolDef
	// Force tells the LLM a tool call must be done, or not.
	Force ToolCallRequest
}

type GenOptionVideo struct {
	// Duration of the video to generate, if supported.
	//
	// Veo 2 supports only between 5 and 8 seconds and Veo 3 only supports 8 seconds.
	Duration time.Duration
	// contains filtered or unexported fields
}

type GenOptionWeb struct {
	// Search specifies if websearch should be enabled. It is generally disabled by default.
	//
	// # Warning
	//
	// This will become a structure to provide information about included and excluded domains, and the user's
	// location.
	Search bool
	// Fetch specifies if web fetch should be enabled. When enabled, the LLM can fetch content from URLs.
	//
	// Currently supported by Anthropic and Gemini.
	Fetch bool
}

type JSONSchema = json.RawMessage

type Job string

type Logprob struct {
	ID      int64   `json:"id,omitzero"`   // Input token ID.
	Text    string  `json:"text,omitzero"` // Text in UTF-8.
	Logprob float64 `json:"logprob"`       // Log probability of the token. It should normally be non-zero but sometimes it is.
}

type Message struct {
	// Requests is the content from the user.
	//
	// It is normally a single message. It is more frequently multiple items when using multi-modal content.
	Requests []Request `json:"request,omitzero"`
	// User must only be used when sent by the user. Only some provider (e.g. OpenAI, Groq, DeepSeek) support it.
	User string `json:"user,omitzero"`

	// Replies is the message from the LLM.
	//
	// It is generally a single reply with text or a tool call. Some models can emit multiple content blocks,
	// either multi modal or multiple text blocks: a code block and a different block with an explanantion. Some
	// models can emit multiple tool calls at once.
	Replies []Reply `json:"reply,omitzero"`

	// ToolCallResult is the result for a tool call that the LLM requested to make.
	//
	// These messages are generated by the "computer".
	ToolCallResults []ToolCallResult `json:"tool_call_results,omitzero"`
	// contains filtered or unexported fields
}

type Messages []Message

type Modalities []scoreboard.Modality

type Modality = scoreboard.Modality

type Model interface {
	GetID() string
	String() string
	// Context returns the number of tokens the model can process as input.
	Context() int64
}

type NoulCriteria struct {
	// True describes what a yes (value near 1) means.
	True DecisionContent `json:"true,omitzero"`
	// False describes what a no (value near 0) means.
	False DecisionContent `json:"false,omitzero"`
}

type Object map[string]any

type Provider interface {
	// Close releases resources held by the provider.
	io.Closer

	// Name returns the name of the provider.
	Name() string
	// ModelID returns the model currently used by the provider. It can be an empty string.
	ModelID() string
	// OutputModalities returns the output modalities supported by this specific client configuration.
	//
	// This states what kind of output the model will generate (text, audio, image, video, decision). It varies per
	// provider and models. The vast majority of providers and models support only output modality like
	// text-only, image-only, etc.
	OutputModalities() Modalities
	// Capabilities returns the optional capabilities this provider supports.
	Capabilities() ProviderCapabilities
	// Scoreboard returns what the provider supports.
	//
	// Some models have more features than others, e.g. some models may be text-only while others have vision or
	// audio support.
	//
	// The client code may be the limiting factor for some models, and not the provider itself.
	//
	// Capability results come from smoke tests; voice catalogs describe
	// provider-advertised choices.
	Scoreboard() scoreboard.Score
	// HTTPClient returns the underlying http client. It may be necessary to use it to fetch the results from
	// the provider. An example is retrieving Veo 3 generated videos from Gemini requires the authentication
	// headers to be set.
	HTTPClient() *http.Client

	// GenSync runs generation synchronously.
	//
	// Multiple options can be mixed together, both standard ones like *GenOptionImage, *GenOptionText,
	// *GenOptionTools and provider-specialized options struct, e.g. *anthropic.GenOptionText, *gemini.GenOption.
	GenSync(ctx context.Context, msgs Messages, opts ...GenOption) (Result, error)
	// GenStream runs generation synchronously, yielding the fragments of replies as the server sends them.
	//
	// No need to accumulate the fragments into a Message since the Result contains the accumulated message.
	GenStream(ctx context.Context, msgs Messages, opts ...GenOption) (iter.Seq[Reply], func() (Result, error))
	// SystemOne answers typed questions about a state without text generation or streaming.
	// It uses the client's configured model. The request is not modified.
	// Requires ProviderCapabilities.SystemOne. Returns base.ErrNotSupported otherwise.
	SystemOne(ctx context.Context, req *SystemOneRequest) (*SystemOneResponse, error)
	// Embed returns one vector per input request in order using the configured model.
	// Configure an explicit embedding model; automatic generation model selection
	// does not choose one. Content blocks and options are not modified; document
	// readers may be read and sought. Input size limits depend
	// on the provider and model. Returns base.ErrNotSupported when unsupported.
	// Provider-specific raw APIs expose additional embedding controls.
	// Capabilities().Embed describes endpoint implementation; the scoreboard
	// Embedding lookup describes tested support for the configured model.
	Embed(ctx context.Context, in *EmbeddingRequest) (*EmbeddingResponse, error)
	// ConnectRealtime opens a bidirectional conversation and waits for setup acceptance.
	// Requires Capabilities().Realtime. Unsupported session features return base.ErrNotSupported.
	ConnectRealtime(ctx context.Context, opts ...RealtimeOption) (RealtimeSession, error)
	// ListModels returns the list of models the provider supports. Not all providers support it, some will
	// return an ErrorNotSupported. For local providers like llamacpp and ollama, they may return only the
	// model currently loaded.
	ListModels(ctx context.Context) ([]Model, error)

	// GenAsync requests a generation and returns a pending job that can be polled.
	//
	// Requires ProviderCapabilities.GenAsync to be set. Returns base.ErrNotSupported otherwise.
	GenAsync(ctx context.Context, msgs Messages, opts ...GenOption) (Job, error)
	// PokeResult requests the state of the job.
	//
	// When the job is still pending, Result.Usage.FinishReason is Pending.
	//
	// Requires ProviderCapabilities.GenAsync to be set. Returns base.ErrNotSupported otherwise.
	PokeResult(ctx context.Context, job Job) (Result, error)
	// CacheAddRequest caches a request.
	//
	// Requires ProviderCapabilities.Caching to be set. Returns base.ErrNotSupported otherwise.
	//
	// # Warning
	//
	// May be changed in the future.
	CacheAddRequest(ctx context.Context, msgs Messages, name, displayName string, ttl time.Duration, opts ...GenOption) (string, error)
	// CacheList lists the caches entries.
	//
	// Requires ProviderCapabilities.Caching to be set. Returns base.ErrNotSupported otherwise.
	//
	// # Warning
	//
	// May be changed in the future.
	CacheList(ctx context.Context) ([]CacheEntry, error)
	// CacheDelete deletes a cache entry.
	//
	// Requires ProviderCapabilities.Caching to be set. Returns base.ErrNotSupported otherwise.
	//
	// # Warning
	//
	// May be changed in the future.
	CacheDelete(ctx context.Context, name string) error
}

type ProviderCapabilities struct {
	// Realtime indicates that the client implements bidirectional realtime sessions,
	// independent of its configured model. Session capabilities are negotiated by
	// ConnectRealtime and reported through RealtimeSession.Info.
	Realtime bool
	// Embed indicates that the client implements the embedding endpoint, independent
	// of its configured model. scoreboard.Score.Embedding reports qualified support;
	// a missing measurement means unknown, not unsupported.
	Embed bool
	// SystemOne indicates the provider implements typed decision inference.
	SystemOne bool
	// GenAsync indicates the provider supports GenAsync and PokeResult for batch operations.
	GenAsync bool
	// Caching indicates the provider supports CacheAddRequest, CacheList, and CacheDelete.
	Caching bool
	// contains filtered or unexported fields
}

type ProviderOption interface {
	Validate() error
}

type ProviderOptionAPIKey string

type ProviderOptionModalities Modalities

type ProviderOptionModel string

type ProviderOptionPreloadedModels []Model

type ProviderOptionRemote string

type ProviderOptionStarterWrapper func(Starter) Starter

type ProviderOptionTransportWrapper func(http.RoundTripper) http.RoundTripper

type ProviderPing interface {
	Provider
	// Ping enables confirming that the provider is accessible, without incurring cost. This is useful for local
	// providers to detect if they are accessible or not.
	Ping(ctx context.Context) error
}

type ProviderScoreboardVariants interface {
	ScoreboardVariants() []ScoreboardVariant
}

type ProviderUnwrap interface {
	Unwrap() Provider
}

type Question struct {
	// Type is how the state is evaluated. It selects which of Noul, Choice or Score must be set.
	Type QuestionType
	// Instructions is what the model should decide or rate. Providers may require it.
	Instructions DecisionContent
	// Noul describes what the yes and the no outcomes mean. It can only be set for QuestionNoul, where it
	// is optional.
	//
	// Recommended reading: https://docs.typesafe.ai/primitives/noul
	Noul *NoulCriteria
	// Choice maps the options of a choice question to their descriptions. It can only be set for
	// QuestionChoice, where at least one option is required. Use nil for an option that needs no extra
	// detail.
	//
	// Recommended reading: https://docs.typesafe.ai/primitives/choice
	Choice map[string]DecisionContent
	// Score lists the levels of a score question rubric, in order, starting at level 0. It can only be set
	// for QuestionScore, where at least one level is required. Use nil for an undescribed level.
	// Providers may impose stricter limits.
	//
	// Recommended reading: https://docs.typesafe.ai/primitives/score
	Score []DecisionContent
}

type QuestionType string

type Questions map[string]*Question

type RateLimit struct {
	Type      RateLimitType
	Period    RateLimitPeriod
	Limit     int64
	Remaining int64
	Reset     time.Time
}

type RateLimitPeriod int32

type RateLimitType int32

type RealtimeCancel struct {
	ResponseID string
}

type RealtimeCapabilities struct {
	AudioCommit    bool
	CancelResponse bool
	ToolResults    bool
	Truncate       bool
	Update         RealtimeUpdateCapabilities
}

type RealtimeContent struct {
	// Audio is owned PCM at Info().OutputFormat for Audio events.
	Audio []byte
	// Text is a delta for Text and transcript events. When Final is true, Text
	// is the complete text and replaces accumulated deltas.
	Text string
	// Reasoning is a delta for Reasoning events.
	Reasoning string
	// Final marks Text as complete for Text and transcript events.
	Final bool
	// ToolCalls contains complete calls with validated JSON arguments and unique
	// nonempty IDs for ToolCalls events. Providers that omit call IDs must assign
	// session-unique IDs and preserve the original provider correlation internally.
	ToolCalls []ToolCall
}

type RealtimeError struct {
	// Code is the provider error code when reported.
	Code string
	// Message is a short, caller-safe description of the failure.
	Message string
	// EventID identifies the rejected client event when reported.
	EventID string
}

type RealtimeEvent struct {
	// Kind identifies the event. GenerationDone means output generation ended,
	// not playback ended. TurnDone means the provider completed its turn, which
	// need not mean session idleness. Interrupted signals the caller to stop
	// playback.
	Kind RealtimeEventKind
	// ResponseID identifies the response within this session. It may be a provider
	// identity or an adapter-assigned identity based on provider turn boundaries.
	ResponseID string
	// ItemID identifies the conversation item when the provider supplies it.
	ItemID string
	// ContentIndex identifies the content part within ItemID.
	ContentIndex int
	// Content is the event payload. Its zero value means the event carries no
	// content.
	Content RealtimeContent
	// Usage is a non-cumulative snapshot for one response. Each Usage event
	// describes its own response; sum them to compute session usage. ResponseID
	// identifies the response when its ownership is known. Limits, when present,
	// replaces the previous rate-limit snapshot.
	Usage *Usage
	// Error carries a recoverable provider error for Error events. The session
	// remains usable. Terminal failures are returned by Receive instead.
	Error *RealtimeError
	// ProviderEvent is provider-specific information for this event. It is nil
	// when the provider supplies none. For RealtimeEventProvider, it is the
	// complete payload.
	ProviderEvent RealtimeProviderEvent
}

type RealtimeEventKind string

type RealtimeInput interface {
	Validate() error
	// contains filtered or unexported methods
}

type RealtimeInputContent struct {
	// Audio appends PCM at Info().InputFormat. It may be empty only with Commit.
	Audio []byte
	// Doc adds a user turn carrying the document. Text may follow it.
	Doc Doc
	// Text adds a user text turn. It may be empty only with Generate.
	Text string
	// ToolResults answers completed calls. It always requests a response.
	ToolResults []ToolCallResult
	// Commit commits buffered audio. Alone it does not request a reply; with
	// Generate it commits before requesting one.
	Commit bool
	// Generate requests a response. It commits nonempty audio first.
	Generate bool
}

type RealtimeOption interface {
	Validate() error
}

type RealtimeOptionAudio struct {
	Voice               string
	InputTranscription  bool
	OutputTranscription bool
}

type RealtimeOptionInstructions string

type RealtimeOptionTools struct {
	Tools []ToolDef
}

type RealtimeProviderEvent interface {
	// RealtimeEventName returns the provider's wire event name.
	RealtimeEventName() string
}

type RealtimeSession interface {
	io.Closer
	// Info returns immutable native formats, accepted input kinds, configured
	// features, and accepted operations after setup.
	Info() RealtimeSessionInfo
	// Send applies one complete command to the session and writes it to the
	// provider. It rejects invalid, unsupported, and out-of-order commands before
	// the first wire write. It serializes concurrent calls, translates the command
	// into the provider's wire messages, and updates local correlation only after
	// every frame is written. Input buffers are borrowed until Send returns and are
	// not retained. A successful return means written, not accepted by the
	// provider. A write failure may leave a partial transaction and terminates the
	// session; do not retry it.
	Send(ctx context.Context, input RealtimeInput) error
	// Receive returns the events as they arrive from the server. Slow consumers
	// apply backpressure; providers must bound frame sizes and any pending events
	// rather than queue indefinitely. Unknown wire events may be skipped or returned
	// as RealtimeEventProvider events; malformed recognized events are errors. Yielded
	// content must satisfy RealtimeContent.Validate. The sequence stops after the
	// first error, including io.EOF for normal peer closure. Breaking out stops
	// receiving without closing the session. Canceling ctx terminates the transport.
	Receive(ctx context.Context) iter.Seq2[RealtimeEvent, error]
}

type RealtimeSessionInfo struct {
	ID           string
	InputFormat  AudioFormat
	OutputFormat AudioFormat
	// InputModalities lists the payload kinds the session encodes: ModalityAudio,
	// ModalityImage, and ModalityText. It states what the transport accepts.
	InputModalities []Modality
	// TurnDetection is the accepted server or manual turn mode.
	TurnDetection RealtimeTurnDetection
	Capabilities  RealtimeCapabilities
}

type RealtimeToolCallCancelledError struct {
	// ToolCallIDs are the cancelled calls matched in the rejected batch.
	ToolCallIDs []string
}

type RealtimeTruncate struct {
	ItemID       string
	ContentIndex int
	AudioEndMS   int64
}

type RealtimeTurnDetection string

type RealtimeUpdate struct {
	Instructions     *string
	Tools            *[]ToolDef
	ToolChoice       *ToolCallRequest
	MaxOutputTokens  *int64
	OutputModalities *Modalities
	TurnDetection    *RealtimeTurnDetection
	Voice            *string
}

type RealtimeUpdateCapabilities struct {
	Instructions       bool
	Tools              bool
	ToolChoice         bool
	ToolChoiceRequired bool
	MaxOutputTokens    bool
	OutputModalities   bool
	TurnDetection      bool
	VoiceBeforeOutput  bool
}

type ReasoningOutput struct{}

type Reply struct {
	// Text is the content of the text message.
	Text string `json:"text,omitzero"`

	// Doc can be audio, video, image, PDF or any other format, including reference text.
	Doc Doc `json:"doc,omitzero"`

	// Citation contains references to source material that support the content.
	Citation Citation `json:"citation,omitzero"`

	// Reasoning is the reasoning done by the LLM. Keep it in conversation history;
	// some models require it when continuing a turn after tool calls.
	Reasoning string `json:"reasoning,omitzero"`

	// ToolCall is a tool call that the LLM requested to make.
	ToolCall ToolCall `json:"tool_call,omitzero"`

	// Opaque is added to keep continuity on the processing. A good example is Anthropic's extended thinking, or
	// server-side tool calling. It must be kept during an exchange.
	//
	// A message with only Opaque set is valid. It can be used in combination with other fields. This field is
	// specific to both the provider and the model.
	//
	// The data must be JSON-serializable.
	Opaque map[string]any `json:"opaque,omitzero"`
	// contains filtered or unexported fields
}

type Request struct {
	// Text is the content of the text message.
	Text string `json:"text,omitzero"`

	// Doc can be audio, video, image, PDF or any other format, including reference text.
	Doc Doc `json:"doc,omitzero"`
	// contains filtered or unexported fields
}

type Result struct {
	Message

	Usage Usage
	// Logprobs is a list of multiple log probabilities, each for a token.
	//
	// The first item of each subslice is the chosen token. The next items are the candidates not chosen.
	//
	// Some providers only return the probability for the chosen tokens and not for the candidates.
	Logprobs [][]Logprob
}

type ScoreLegend map[string]DecisionContent

type ScoreboardVariant struct {
	// Name is the display name for this variant, e.g. "Intl", "US".
	Name string
	// Score is the scoreboard data for this variant.
	Score scoreboard.Score
}

type Starter func(ctx context.Context, args []string) (stdin io.WriteCloser, stdout io.ReadCloser, wait func() error, err error)

type SystemOneRequest struct {
	// State is required unless Docs contains one application/json document.
	State     DecisionContent `json:"state"`
	Questions Questions       `json:"questions"`
	// Docs contains inline document attachments. When State is unset, one application/json document
	// supplies the state instead. Supported attachment types depend on the provider and model.
	// Remote URLs are not supported.
	Docs []Doc `json:"docs,omitzero"`
}

type SystemOneResponse struct {
	// Answers holds one answer per question, keyed by the question name.
	Answers Answers `json:"answers"`
	// Usage is the token usage of the request.
	Usage DecisionUsage `json:"usage"`
}

type Text string

type ToolCall struct {
	ID        string `json:"id,omitzero"`        // Unique identifier for the tool call. Necessary for parallel tool calling.
	Name      string `json:"name,omitzero"`      // Tool being called.
	Arguments string `json:"arguments,omitzero"` // encoded as JSON

	// Opaque is added to keep continuity on the processing. A good example is Anthropic's extended thinking. It
	// must be kept during an exchange.
	//
	// A message with only Opaque set is valid.
	Opaque map[string]any `json:"opaque,omitzero"`
	// contains filtered or unexported fields
}

type ToolCallRequest int

type ToolCallResult struct {
	ID     string `json:"id,omitzero"`
	Name   string `json:"name,omitzero"`
	Result string `json:"result,omitzero"`
	// contains filtered or unexported fields
}

type ToolDef struct {
	// Name must be unique among all tools.
	Name string
	// Description must be a LLM-friendly short description of the tool.
	Description string
	// Callback is the function to call with the inputs.
	// It must accept a context.Context one struct pointer as input: (ctx context.Context, input *struct{}). The
	// struct must use json_schema to be serializable as JSON.
	// It must return the result and an error: (string, error).
	Callback any
	// InputSchemaOverride overrides the schema deduced from the Callback's second argument. It's meant to be
	// used when an enum or a description is set dynamically, or with complex if/then/else that would be tedious
	// to describe as struct tags.
	//
	// It is okay to initialize Callback, then take the return value of GetInputSchema() to initialize InputSchemaOverride, then mutate it.
	InputSchemaOverride JSONSchema
	// contains filtered or unexported fields
}

type Usage struct {
	// Token usage for the current request.
	InputTokens       int64
	InputCachedTokens int64
	ReasoningTokens   int64
	OutputTokens      int64
	TotalTokens       int64
	// ContextTokens is the number of tokens in the context window after the
	// request. Zero when the provider does not report it.
	ContextTokens int64
	// ContextWindow is the maximum number of tokens the context window holds.
	// Zero when the provider does not report it.
	ContextWindow int64
	// FinishReason indicates why the model stopped generating tokens.
	FinishReason FinishReason
	// ServiceTier is the quality of service tier used to process the request,
	// as reported by the provider. Common values include "standard", "batch",
	// "flex", "default", "auto", etc. Empty when not reported.
	ServiceTier string
	// Limits contains a list of rate limit details from the provider.
	Limits []RateLimit
}