ai

type AssistantMessage struct {
	Parts []AssistantPart
}

type AssistantPart interface {
	Part
	// contains filtered or unexported methods
}

type Capabilities struct {
	// Text reports whether the model generates text.
	Text bool
	// Vision reports whether the model accepts image input.
	Vision bool
	// Documents reports whether the model accepts document/file input.
	Documents bool
	// AudioInput reports whether the model accepts audio input.
	AudioInput bool
	// VideoInput reports whether the model accepts video input.
	VideoInput bool
	// Tools reports whether the model supports tool / function calling.
	Tools bool
	// StructuredOutput reports whether the model supports schema-constrained
	// JSON output.
	StructuredOutput bool
	// Reasoning reports whether the model exposes reasoning ("thinking")
	// controls and content.
	Reasoning bool
	// ImageGeneration reports whether the model can generate images.
	ImageGeneration bool
	// Embeddings reports whether the model produces embeddings.
	Embeddings bool
	// Reranking reports whether the model performs document reranking.
	Reranking bool
	// PromptCaching reports whether the provider supports prompt-cache reuse
	// or cache-usage reporting for this model. Caching may be automatic or
	// explicitly controlled by the request.
	PromptCaching bool
	// TokenCounting reports whether the model exposes a server-side token-count
	// operation without running inference.
	TokenCounting bool
	// WebSearch reports whether the model natively supports provider-executed
	// web search.
	WebSearch bool
	// CodeExecution reports whether the model natively supports server-side
	// code execution.
	CodeExecution bool
}

type CapabilityDeclaration struct {
	// Name is the stable field name, for example "vision" or "audio_input".
	Name string
	// Value is the declared value.
	Value bool
}

type CapabilityOverride struct {
	// Text reports whether the model generates text.
	Text *bool
	// Vision reports whether the model accepts image input.
	Vision *bool
	// Documents reports whether the model accepts document/file input.
	Documents *bool
	// AudioInput reports whether the model accepts audio input.
	AudioInput *bool
	// VideoInput reports whether the model accepts video input.
	VideoInput *bool
	// Tools reports whether the model supports tool / function calling.
	Tools *bool
	// StructuredOutput reports whether the model supports schema-constrained
	// JSON output.
	StructuredOutput *bool
	// Reasoning reports whether the model exposes reasoning controls/content.
	Reasoning *bool
	// ImageGeneration reports whether the model can generate images.
	ImageGeneration *bool
	// Embeddings reports whether the model produces embeddings.
	Embeddings *bool
	// Reranking reports whether the model performs document reranking.
	Reranking *bool
	// PromptCaching reports whether the provider supports prompt-cache reuse
	// or cache-usage reporting for this model.
	PromptCaching *bool
	// TokenCounting reports whether the model exposes server-side token
	// counting without running inference.
	TokenCounting *bool
	// WebSearch reports whether the model supports provider-executed web
	// search.
	WebSearch *bool
	// CodeExecution reports whether the model supports server-side code
	// execution.
	CodeExecution *bool
}

type Citation struct {
	// URL is the web address of the referenced source.
	URL string `json:"url"`
	// Title is the human-readable title of the document or webpage.
	Title string `json:"title,omitempty"`
	// Snippet is the extracted content snippet that grounded the answer.
	Snippet string `json:"snippet,omitempty"`
	// Index is the reference index corresponding to citation markers in the text.
	Index int `json:"index,omitempty"`
	// TextRange is the character offset span in the generated text supported by
	// this citation.
	TextRange *TextRange `json:"text_range,omitempty"`
}

type EmbeddedResourcePart struct {
	// URI locates the originating resource. It is required.
	URI string
	// MIMEType describes Text or Blob. It is required for Blob.
	MIMEType string
	// Text is the body of a textual resource.
	Text string
	// Blob is the raw body of a binary resource.
	Blob []byte
}

type EmbeddingEncodingFormat string

type EmbeddingModel interface {
	Embed(ctx context.Context, req EmbeddingRequest) (*EmbeddingResponse, error)
	Provider() Provider
	ModelID() string
}

type EmbeddingRequest struct {
	// Input is the texts to embed. Order is preserved in the response.
	Input []string
	// Dimensions optionally requests reduced-dimension vectors on models that
	// support it. Nil uses the model default.
	Dimensions *int

	// TaskType optionally specifies downstream task optimization for models that
	// support asymmetric embeddings (such as Gemini). Empty leaves task optimization
	// to provider default.
	TaskType EmbeddingTaskType
	// Title optionally specifies the document title when TaskType is
	// [EmbeddingTaskTypeDocument]. Providers that do not use document titles ignore this.
	Title string
	// EncodingFormat optionally requests a compact transfer format (such as Base64)
	// on providers that support it. Regardless of transfer format, the returned
	// [EmbeddingResponse.Embeddings] are decoded as [][]float32.
	EncodingFormat EmbeddingEncodingFormat

	// ProviderOptions passes provider-specific extensions, keyed like
	// [Request.ProviderOptions].
	ProviderOptions map[Provider]any
}

type EmbeddingResponse struct {
	Embeddings [][]float32
	Usage      Usage
	Raw        JSON
}

type EmbeddingTaskType string

type Error struct {
	// Provider is the adapter that produced the error.
	Provider Provider
	// StatusCode is the HTTP status, or 0 for transport/decoding errors.
	StatusCode int
	// Type is the provider's error type string (for example
	// "rate_limit_error"), when present.
	Type string
	// Code is the provider's error code, when present.
	Code string
	// Message is the human-readable error message.
	Message string
	// RetryAfter is the delay requested by a Retry-After header, when present.
	RetryAfter time.Duration
	// Raw is the provider's error body, when available.
	Raw []byte
	// contains filtered or unexported fields
}

type FilePart struct {
	Source MediaSource
	// Name is an optional human-readable filename, forwarded to providers that
	// accept one.
	Name string
}

type FinishReason string

type GeneratedImage struct {
	// Data is the inline image bytes; empty when the provider returned a URL.
	Data []byte
	// MIMEType is the image's media type (for example "image/webp"). It is
	// empty when the provider reported no usable format.
	MIMEType string
	// URL is the provider-hosted link to the image. It is temporary (OpenAI
	// keeps it valid for 60 minutes). The adapter never downloads it; fetch it
	// yourself if you need bytes.
	URL string
	// RevisedPrompt is the prompt the provider reports having actually used,
	// when it does (OpenAI's dall-e-3). It is empty for providers that do not
	// report one.
	RevisedPrompt string
}

type GroundingMetadata struct {
	// WebSearchQueries lists queries formulated by the model during generation.
	WebSearchQueries []string `json:"web_search_queries,omitempty"`
	// Raw preserves provider-specific grounding structures.
	Raw any `json:"raw,omitempty"`
}

type ImageEditRequest struct {
	// Prompt describes the desired edit.
	Prompt string
	// Images are the source images, each carrying inline bytes, a URL, or a
	// provider file ID. Providers cap the count (OpenAI: 1 to 16).
	Images []ImagePart
	// Mask is an optional PNG whose transparent pixels mark the region to
	// edit. It applies to Images[0].
	Mask *ImagePart
	// N is how many images to generate; zero means one.
	N int
	// Size is the provider-specific dimensions string. Empty uses the provider
	// default.
	Size string
	// Quality is the provider-specific quality tier. Empty uses the provider
	// default.
	Quality string
	// OutputFormat is the desired encoding ("png", "jpeg", or "webp"). Empty
	// uses the provider default. Providers that emit a single format ignore
	// it.
	OutputFormat string

	// ProviderOptions passes provider-specific extensions, keyed like
	// [Request.ProviderOptions].
	ProviderOptions map[Provider]any
}

type ImageEditor interface {
	// EditImage applies an edit request and returns the completed response.
	EditImage(ctx context.Context, req ImageEditRequest) (*ImageResponse, error)
}

type ImageModel interface {
	GenerateImages(ctx context.Context, req ImageRequest) (*ImageResponse, error)
	Provider() Provider
	ModelID() string
}

type ImagePart struct {
	Source MediaSource
}

type ImageRequest struct {
	// Prompt describes the desired image.
	Prompt string
	// N is how many images to generate; zero means one.
	N int
	// Size is the provider-specific dimensions string (for example
	// "1024x1024"). Empty uses the provider default.
	Size string
	// Quality is the provider-specific quality tier (for example "high").
	// Empty uses the provider default.
	Quality string
	// OutputFormat is the desired encoding ("png", "jpeg", or "webp"). Empty
	// uses the provider default. Providers that emit a single format ignore
	// it.
	OutputFormat string

	// ProviderOptions passes provider-specific extensions, keyed like
	// [Request.ProviderOptions].
	ProviderOptions map[Provider]any
}

type ImageResponse struct {
	// Images are the produced images, in provider order.
	Images []GeneratedImage
	// Usage is the token accounting for the request; zero when unreported.
	Usage ImageUsage
	// CreatedAt is when the provider created the response. The zero time means
	// the provider did not report it.
	CreatedAt time.Time
	// OutputFormat is the format the provider reports having produced (for
	// example "webp"); empty when unreported.
	OutputFormat string
	// Size is the produced dimensions string the provider reports (for example
	// "1024x1536"); empty when unreported.
	Size string
	// Quality is the effective quality tier the provider reports; empty when
	// unreported.
	Quality string
	// Background is the effective background the provider reports (for example
	// "transparent"); empty when unreported.
	Background string
	// Raw is the provider's response body, untouched. Providers that return
	// inline image payloads in the body keep them here as well, so Raw is
	// larger than the decoded images.
	Raw JSON
}

type ImageStream = iter.Seq2[ImageStreamEvent, error]

type ImageStreamEvent struct {
	// Type identifies the event.
	Type ImageStreamEventType
	// Index is the 0-based index of the partial image. It is always 0 on the
	// completed event, which carries no index of its own.
	Index int
	// Image is the event's image: inline bytes for partials and for the final
	// image of providers that stream data (OpenAI never streams URLs).
	Image GeneratedImage
	// Usage is the request's token accounting. It is non-nil only on the
	// completed event, and only when the provider reported it.
	Usage *ImageUsage
}

type ImageStreamEventType string

type ImageStreamer interface {
	// StreamImages streams a generation request.
	StreamImages(ctx context.Context, req ImageRequest) ImageStream
	// StreamImageEdits streams an edit request.
	StreamImageEdits(ctx context.Context, req ImageEditRequest) ImageStream
}

type ImageUsage struct {
	Usage
	// TotalTokens is the provider-reported total for the call.
	TotalTokens int
	// InputTextTokens is the input text portion, when the provider breaks it
	// out.
	InputTextTokens int
	// InputImageTokens is the input image portion, when the provider breaks it
	// out.
	InputImageTokens int
	// OutputTextTokens is the output text portion, when the provider breaks it
	// out.
	OutputTextTokens int
	// OutputImageTokens is the output image portion, when the provider breaks
	// it out.
	OutputImageTokens int
}

type ImageVariationRequest struct {
	// Image is the source image. Providers that require inline bytes reject
	// other sources.
	Image ImagePart
	// N is how many images to generate; zero means one.
	N int
	// Size is the provider-specific dimensions string. Empty uses the provider
	// default.
	Size string

	// ProviderOptions passes provider-specific extensions, keyed like
	// [Request.ProviderOptions].
	ProviderOptions map[Provider]any
}

type ImageVariator interface {
	// CreateVariations applies a variation request and returns the completed
	// response.
	CreateVariations(ctx context.Context, req ImageVariationRequest) (*ImageResponse, error)
}

type JSON = json.RawMessage

type LanguageModel interface {
	// Generate performs a blocking request and returns the completed response.
	Generate(ctx context.Context, req Request) (*Response, error)
	// Stream performs a streaming request. Errors — including connection
	// failures — surface through the returned sequence on first iteration.
	// Breaking out of the range loop cancels the request.
	Stream(ctx context.Context, req Request) Stream
	// Provider identifies the adapter.
	Provider() Provider
	// ModelID is the model this instance is bound to.
	ModelID() string
	// Capabilities reports, best effort, what the bound model supports.
	Capabilities() Capabilities
}

type LogProbsConfig struct {
	Enabled bool
	Top     int
}

type MediaSource struct {
	// ID references a file already uploaded to the target provider. IDs are
	// provider-scoped opaque values.
	ID string
	// URL is a remote location for the media. Providers that only accept
	// inline bytes will reject a URL source. Provider file URIs also use this
	// field (for example a Gemini Files API URI).
	URL string
	// Data is the raw media bytes, used when the media is inlined rather than
	// referenced by URL.
	Data []byte
	// MIMEType is the IANA media type of Data (for example "image/jpeg"). It
	// is required for a Data source and optional for a URL source.
	MIMEType string
}

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

type Messages []Message

type Middleware func(LanguageModel) LanguageModel

type Part interface {
	// contains filtered or unexported methods
}

type Provider string

type ReasoningConfig struct {
	// Mode controls whether and how the provider enables reasoning.
	Mode ReasoningMode
	// Effort is the portable knob; prefer it for cross-provider code.
	Effort ReasoningEffort
	// BudgetTokens optionally pins an explicit thinking-token budget for
	// providers that accept one (Anthropic, Gemini). Zero leaves budget
	// selection to the effort mapping or provider default.
	BudgetTokens int
	// IncludeSummary asks providers that can return a reasoning summary
	// (OpenAI Responses) to include it. Providers that always stream reasoning
	// content ignore this.
	IncludeSummary bool
}

type ReasoningEffort string

type ReasoningMode string

type ReasoningPart struct {
	// Text is the reasoning content. It is empty when Redacted is true.
	Text string
	// Signature is opaque provider continuation state for the reasoning block.
	// Preserve it when echoing reasoning back to the same provider.
	Signature string
	// Redacted reports that the provider withheld the reasoning content while
	// still requiring the block to be echoed back (via Signature) to continue
	// the turn.
	Redacted bool
}

type Request struct {
	// Messages is the conversation so far, oldest first.
	Messages Messages

	// Tools the model may call.
	Tools []Tool
	// ToolChoice constrains tool usage. The zero value is provider default.
	ToolChoice ToolChoice

	// Temperature controls randomness. Nil sends nothing.
	Temperature *float64
	// TopP is the nucleus-sampling cutoff. Nil sends nothing.
	TopP *float64
	// TopK limits sampling to the k most likely tokens. Nil sends nothing.
	TopK *int
	// Seed requests deterministic sampling when the provider supports it.
	Seed *int64
	// FrequencyPenalty discourages tokens based on occurrence frequency.
	FrequencyPenalty *float64
	// PresencePenalty discourages tokens that have already appeared.
	PresencePenalty *float64
	// LogProbs requests token log probabilities.
	LogProbs *LogProbsConfig
	// MaxTokens caps generated tokens. Nil lets the adapter choose: providers
	// that require the field (Anthropic) get a sensible default; others get
	// nothing.
	MaxTokens *int
	// Stop lists sequences that end generation.
	Stop []string

	// ResponseFormat requests schema-constrained JSON output. See
	// [GenerateTyped] for the typed convenience wrapper.
	ResponseFormat *ResponseFormat
	// Reasoning requests and tunes model reasoning.
	Reasoning *ReasoningConfig

	// ProviderOptions passes provider-specific extensions that have no
	// portable representation. Each adapter looks up its own [Provider] key
	// and type-asserts the value to its documented options type; unknown keys
	// are ignored.
	ProviderOptions map[Provider]any
}

type RerankModel interface {
	Rerank(ctx context.Context, req RerankRequest) (*RerankResponse, error)
	Provider() Provider
	ModelID() string
}

type RerankRequest struct {
	// Query is the search intent or reference text to rank candidate documents against.
	Query string
	// Documents is the list of candidate texts to rank. Order is indexed from 0
	// and mapped to [RerankResult.Index].
	Documents []string
	// TopN optionally limits the number of returned results. If set, it must be
	// greater than 0. If nil, all candidate documents are ranked and returned.
	TopN *int
	// ReturnDocuments optionally requests that original document texts be returned
	// in [RerankResult.Document].
	ReturnDocuments bool

	// ProviderOptions passes provider-specific extensions, keyed like
	// [Request.ProviderOptions].
	ProviderOptions map[Provider]any
}

type RerankResponse struct {
	Results []RerankResult
	Usage   Usage
	Raw     JSON
}

type RerankResult struct {
	// Index is the zero-based position of the document in the original [RerankRequest.Documents].
	Index int
	// RelevanceScore is the relevance score assigned by the model (higher is more relevant).
	RelevanceScore float64
	// Document is the original document text, populated if ReturnDocuments was true
	// or if the provider returns it.
	Document string
}

type ResourceLinkPart struct {
	// URI locates the resource. It is required.
	URI string
	// Name is the machine-readable resource name supplied by the source.
	Name string
	// Title is a human-readable display name supplied by the source.
	Title string
	// Description describes the resource.
	Description string
	// MIMEType is the expected media type of the resource, when known.
	MIMEType string
}

type Response struct {
	// ID is the provider's response identifier, when supplied.
	ID string
	// Model is the model that actually served the request, as reported by the
	// provider (it may be more specific than the requested alias).
	Model string
	// Provider identifies which adapter produced this response.
	Provider Provider

	// Message is the assistant turn: text, tool calls, and reasoning parts in
	// model output order. Append it to the conversation to continue the turn.
	Message AssistantMessage

	// FinishReason is why generation stopped.
	FinishReason FinishReason
	// Usage is the token accounting for this request.
	Usage Usage

	// Citations lists source attributions produced by search or grounding tools.
	Citations []Citation
	// Grounding contains query-level grounding details when provided by the model.
	Grounding *GroundingMetadata

	// Warnings reports anything the adapter did not send exactly as
	// configured, for example a field the endpoint does not implement. An
	// empty slice means the request was encoded as written.
	Warnings []Warning

	// Raw is the provider's response body, untouched. It is an escape hatch
	// for provider-specific fields; do not parse it in portable code.
	Raw JSON
}

type ResponseFormat struct {
	// Name labels the schema. Providers that require a name (OpenAI) get
	// "output" when empty.
	Name string
	// Description optionally tells the model what the output represents.
	Description string
	// Schema constrains the output. It must describe a JSON object at the top
	// level, which is what every provider requires.
	Schema *Schema
	// Strict requests provider-side exact-schema enforcement where available
	// (OpenAI). Other providers ignore it.
	Strict bool
}

type Schema struct {
	// RawJSON is an opaque JSON Schema object or boolean. When set, it takes
	// precedence over all typed fields during marshaling. Use ParseSchema for
	// dynamic schemas that must be forwarded without normalization.
	RawJSON json.RawMessage

	// Type is a JSON Schema type: "object", "array", "string", "number",
	// "integer", "boolean", or "null".
	Type string
	// Types represents a union of non-null JSON Schema types. When non-empty,
	// it takes precedence over Type. Nullable adds "null" to either form.
	Types       []string
	Description string

	// Nullable widens Type to also accept null (serialized as
	// ["<type>","null"]). OpenAI strict mode expresses optional fields this
	// way.
	Nullable bool

	// Object schemas.
	Properties map[string]*Schema
	Required   []string
	// AdditionalProperties may be a bool or a *Schema. OpenAI strict mode
	// requires it to be false on every object; adapters set that when the
	// caller has not.
	AdditionalProperties any

	// Array schemas.
	Items *Schema

	// String/number constraints.
	Enum    []any
	Format  string
	Pattern string

	// Extra contains JSON Schema keywords without typed fields, such as
	// oneOf, $defs, minimum, and default. Typed fields take precedence over
	// entries with the same keyword.
	Extra map[string]json.RawMessage
}

type Stream = iter.Seq2[StreamEvent, error]

type StreamEvent struct {
	Type StreamEventType

	// Provider, ID, and Model are set on message_start.
	Provider Provider
	ID       string
	Model    string

	// Text is the fragment for text_delta and reasoning_delta.
	Text string
	// Signature carries opaque provider continuation state on reasoning_delta
	// events (for example Anthropic signature_delta, Gemini thoughtSignature,
	// or an OpenAI Responses reasoning item). It may arrive with an empty Text
	// and applies to the reasoning part being accumulated.
	Signature string

	// ToolCallIndex orders concurrent tool calls within the response; it is
	// set on all tool_call_* events.
	ToolCallIndex int
	// ToolCallID and ToolCallName are set on tool_call_start.
	ToolCallID   string
	ToolCallName string
	// ArgsDelta is the JSON-arguments fragment for tool_call_delta.
	ArgsDelta string

	// Citation is set on citation events.
	Citation *Citation

	// FinishReason and Usage are set on message_end. Usage is nil when the
	// provider does not report it. Grounding carries search metadata when
	// available. Warnings reports anything the adapter did not send exactly as
	// configured; it is set on message_end and is empty when the request was
	// encoded as written.
	FinishReason FinishReason
	Usage        *Usage
	Grounding    *GroundingMetadata
	Warnings     []Warning
}

type StreamEventType string

type StructuredContentPart struct {
	// Data is the structured payload. It must be a complete JSON object.
	Data JSON
}

type SystemMessage struct {
	Parts []SystemPart
}

type SystemPart interface {
	Part
	// contains filtered or unexported methods
}

type TextPart struct {
	Text string
}

type TextRange struct {
	Start int `json:"start"`
	End   int `json:"end"`
}

type TokenCounter interface {
	CountTokens(ctx context.Context, req Request) (int, error)
}

type Tool struct {
	// Kind specifies the execution model of the tool. The zero value is
	// [ToolKindFunction].
	Kind ToolKind

	// Name identifies the tool. Providers restrict names to
	// letters/digits/underscores/dashes; stick to that subset for portability.
	Name string
	// Description tells the model what the tool does and when to use it.
	Description string
	// InputSchema describes the arguments object as JSON Schema. A nil schema
	// means the tool takes no arguments.
	InputSchema *Schema

	// ProviderType is the wire type discriminator used by the provider
	// (e.g. "web_search", "google_search", "code_execution").
	ProviderType string
	// ProviderData carries provider-specific tool configuration.
	ProviderData any
	// Disabled when true causes the tool to be omitted from the request.
	Disabled bool
}

type ToolCallPart struct {
	// ID uniquely identifies this call within the conversation. Gemini does
	// not supply IDs on the wire; its adapter synthesizes stable ones.
	ID string
	// Name is the tool being called.
	Name string
	// Args is the raw JSON arguments object produced by the model.
	Args JSON
}

type ToolChoice struct {
	Mode ToolChoiceMode
	// Name is the tool to force when Mode is [ToolChoiceTool].
	Name string
}

type ToolChoiceMode string

type ToolKind string

type ToolMessage struct {
	Parts []ToolResultPart
}

type ToolResultPart struct {
	// ToolCallID matches the [ToolCallPart.ID] this result answers.
	ToolCallID string
	// Name is the tool that produced the result. Some providers require it;
	// others ignore it.
	Name string
	// Content is the tool output. Text is the common case, but results may be
	// multi-modal (for example an image returned by a tool).
	Content []Part
	// IsError reports that the tool failed; the model is told the call errored.
	IsError bool
}

type Usage struct {
	// InputTokens is the prompt size, including cached tokens.
	InputTokens int
	// OutputTokens is the generated size, including reasoning tokens where
	// the provider counts them there.
	OutputTokens int
	// ReasoningTokens is the portion of output spent on reasoning, when
	// reported separately.
	ReasoningTokens int
	// CachedInputTokens is the portion of input served from a prompt cache,
	// when reported.
	CachedInputTokens int
	// CacheWriteTokens is the portion of input written to a prompt cache
	// (Anthropic cache_creation), when reported.
	CacheWriteTokens int
}

type UserMessage struct {
	Parts []UserPart
}

type UserPart interface {
	Part
	// contains filtered or unexported methods
}

type Warning struct {
	// Type classifies the notice.
	Type WarningType
	// Feature names the field or capability the notice is about, for example
	// "reasoning_effort", "response_format", or a provider tool name.
	Feature string
	// Details explains what happened and why, in one sentence.
	Details string
}

type WarningType string