model

type APIError struct {
	Provider   string
	StatusCode int
	// Type is the provider's error type, or its code when it reports no
	// type.
	Type string
	// Code is the provider's error code, when it reports one alongside or
	// instead of a type.
	Code    string
	Message string
	// RetryAfter is the delay requested by the provider, when available.
	RetryAfter time.Duration
}

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

type Describer interface {
	Describe() Description
}

type Description struct {
	// Provider is the gen_ai.provider.name, such as "openai", "anthropic"
	// or "gcp.gemini".
	Provider string
	// Operation is the gen_ai.operation.name of a call, such as "chat" or
	// "generate_content".
	Operation string
	// Model is the model used when a request names none.
	Model string
	// ServerAddress and ServerPort locate the API endpoint.
	ServerAddress string
	ServerPort    int
}

type Effort string

type FinishReason string

type Func func(ctx context.Context, req *Request) (*Response, error)

type Message struct {
	Role     Role           `json:"role"`
	Parts    []Part         `json:"parts"`
	Name     string         `json:"name,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type Model interface {
	// Generate returns a complete response.
	Generate(ctx context.Context, req *Request) (*Response, error)
	// Stream yields incremental events and finishes with a StreamDone event
	// that carries the complete response. A non-nil error ends the stream.
	Stream(ctx context.Context, req *Request) iter.Seq2[*StreamEvent, error]
}

type Part struct {
	Type PartType `json:"type"`

	// Text holds text content, the visible reasoning for PartReasoning, or
	// the transcript of audio a model produced.
	Text string `json:"text,omitempty"`

	// MediaType, Data and URL describe an image, document, audio or video
	// part: its content is either Data, a URL or FileID. Data is encoded as
	// base64 in JSON.
	MediaType string `json:"media_type,omitempty"`
	Data      []byte `json:"data,omitempty"`
	URL       string `json:"url,omitempty"`
	// FileID refers to a file uploaded to the provider's Files API, such
	// as an OpenAI or Anthropic file ID, in place of Data or URL. Gemini
	// files are referenced by their URI in URL. Set Provider to the
	// provider that issued the ID, so other providers reject the part
	// instead of sending an ID they do not know.
	FileID string `json:"file_id,omitempty"`
	// Filename names a document, audio or video part. Providers send it as
	// the file name or title where the API takes one.
	Filename string `json:"filename,omitempty"`
	// Detail is the resolution at which providers that support it process
	// an image or video: "low", "medium", "high" or "auto". It maps to
	// OpenAI's detail and Gemini's mediaResolution.
	Detail string `json:"detail,omitempty"`
	// Citations asks providers that support it, Anthropic and Bedrock, to
	// cite a document part in the answer.
	Citations bool `json:"citations,omitempty"`

	// Signature is an opaque provider token that must be returned unchanged
	// with the part, such as a reasoning signature.
	Signature string `json:"signature,omitempty"`
	// Redacted marks reasoning whose content is encrypted in Data.
	Redacted bool `json:"redacted,omitempty"`

	ToolCall   *ToolCall   `json:"tool_call,omitempty"`
	ToolResult *ToolResult `json:"tool_result,omitempty"`

	// Provider and Raw hold a PartRaw block. Provider also names the
	// provider that issued Signature, when the provider records it, so
	// signatures are not sent to providers that cannot verify them.
	Provider string          `json:"provider,omitempty"`
	Raw      json.RawMessage `json:"raw,omitempty"`
}

type PartType string

type PermanentError struct{ Err error }

type Reasoning struct {
	// Effort is the reasoning effort; empty leaves it to the provider.
	Effort Effort `json:"effort,omitempty"`
	// Display controls whether reasoning text is returned, for providers
	// that support it; empty leaves it to the provider.
	Display ReasoningDisplay `json:"display,omitempty"`
	// BudgetTokens limits reasoning tokens for providers that use budgets.
	BudgetTokens int `json:"budget_tokens,omitempty"`
}

type ReasoningDisplay string

type Request struct {
	// Model overrides the provider's configured model name.
	Model string `json:"model,omitempty"`
	// System is the system prompt.
	System   string     `json:"system,omitempty"`
	Messages []*Message `json:"messages"`

	Tools      []*ToolSpec `json:"tools,omitempty"`
	ToolChoice *ToolChoice `json:"tool_choice,omitempty"`

	MaxTokens   int      `json:"max_tokens,omitempty"`
	Temperature *float64 `json:"temperature,omitempty"`
	// Seed asks providers that support it, such as OpenAI and Gemini, for
	// deterministic sampling.
	Seed *int     `json:"seed,omitempty"`
	TopP *float64 `json:"top_p,omitempty"`
	Stop []string `json:"stop,omitempty"`

	Reasoning      *Reasoning      `json:"reasoning,omitempty"`
	ResponseFormat *ResponseFormat `json:"response_format,omitempty"`

	// ProviderOptions holds provider-specific request fields, keyed by the
	// provider adapter: "openai", "anthropic", "gemini" or "bedrock", the
	// name in Part.Provider. An adapter merges only its own map into the
	// request body, overriding generated fields with the same name, so one
	// request can carry options for several providers, as a fallback
	// between providers needs.
	ProviderOptions map[string]map[string]any `json:"provider_options,omitempty"`
}

type Response struct {
	ID           string       `json:"id,omitempty"`
	Model        string       `json:"model,omitempty"`
	Message      *Message     `json:"message"`
	FinishReason FinishReason `json:"finish_reason"`
	Usage        Usage        `json:"usage"`
}

type ResponseFormat struct {
	Name   string          `json:"name"`
	Schema json.RawMessage `json:"schema"`
	Strict bool            `json:"strict,omitempty"`
}

type Role string

type StreamEvent struct {
	Type StreamEventType `json:"type"`
	// Index is the position of the part that Delta extends.
	Index int `json:"index"`
	// Delta is a partial part. Text, Signature and ToolCall.Arguments are
	// appended to the part at Index; other fields are set when first seen.
	Delta *Part `json:"delta,omitempty"`
	// Response is set on StreamDone.
	Response *Response `json:"response,omitempty"`
}

type StreamEventType string

type ToolCall struct {
	ID        string          `json:"id"`
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments,omitempty"`
}

type ToolChoice struct {
	Mode ToolChoiceMode `json:"mode"`
	Name string         `json:"name,omitempty"`
}

type ToolChoiceMode string

type ToolGrammar struct {
	// Syntax is the grammar language, "lark" or "regex".
	Syntax string `json:"syntax"`
	// Definition is the grammar. An empty definition accepts any text.
	Definition string `json:"definition,omitempty"`
}

type ToolResult struct {
	CallID  string `json:"call_id"`
	Name    string `json:"name,omitempty"`
	Content string `json:"content"`
	// Parts holds content that follows Content, such as the images and
	// documents a tool returned. Providers put them in the tool result
	// where the API allows it, or else in a user message after the
	// results; see their package documentation.
	Parts   []Part `json:"parts,omitempty"`
	IsError bool   `json:"is_error,omitempty"`
	// Metadata is what the tool reported for the application in
	// tool.Result.Metadata. It is not sent to models, and is stored with
	// the conversation, so its values should be encodable as JSON.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type ToolSpec struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// Parameters is a JSON Schema object describing the arguments.
	Parameters json.RawMessage `json:"parameters,omitempty"`
	// Strict asks providers that support it to guarantee schema-valid
	// arguments.
	Strict bool `json:"strict,omitempty"`
	// Grammar, when set, makes the tool freeform where the provider
	// supports it, as the OpenAI Responses API does: the model writes the
	// input as plain text matching the grammar instead of JSON, and the
	// provider passes the text as the string argument FreeformInput.
	// Other providers send Parameters, which must declare that argument.
	Grammar *ToolGrammar `json:"grammar,omitempty"`
}

type Usage struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
	// CacheReadTokens and CacheWriteTokens count prompt-cache activity. They
	// are reported separately from InputTokens by providers that distinguish
	// them.
	CacheReadTokens  int `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens int `json:"cache_write_tokens,omitempty"`
	// ReasoningTokens is the portion of OutputTokens spent on reasoning when
	// the provider reports it.
	ReasoningTokens int `json:"reasoning_tokens,omitempty"`
	// Requests and ToolCalls count the model calls and executed tool calls
	// of a run, including those of nested runs such as sub-agents. The
	// runtime counts them; providers leave them zero.
	Requests  int `json:"requests,omitempty"`
	ToolCalls int `json:"tool_calls,omitempty"`
}