api

type AISDKError struct {
	// Name is the name of the error
	Name string

	// Message is the error message
	Message string

	// Cause is the underlying cause of the error, if any
	Cause any
}

type APICallError struct {
	*AISDKError

	// URL of the API endpoint that was called
	URL *url.URL

	// Request contains the original HTTP request
	Request *http.Request

	// StatusCode is the HTTP status code of the response if any
	StatusCode int

	// Response contains the original HTTP response
	Response *http.Response

	// Data contains additional error data, if any
	Data any
}

type AssistantMessage struct {
	// Content contains an array of content blocks (text or tool calls)
	Content []ContentBlock `json:"content"`

	// ProviderMetadata contains additional provider-specific metadata.
	// They are passed through to the provider from the AI SDK and enable
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type CallOptions struct {
	// MaxOutputTokens specifies the maximum number of tokens to generate
	MaxOutputTokens int `json:"max_output_tokens,omitzero"`

	// Temperature controls randomness in the model's output.
	// It is recommended to set either Temperature or TopP, but not both.
	Temperature *float64 `json:"temperature,omitzero"`

	// TopP controls nucleus sampling.
	// It is recommended to set either Temperature or TopP, but not both.
	TopP float64 `json:"top_p,omitzero"`

	// TopK limits sampling to the top K options for each token.
	// Used to remove "long tail" low probability responses.
	// Recommended for advanced use cases only.
	TopK int `json:"top_k,omitzero"`

	// PresencePenalty affects the likelihood of the model repeating
	// information that is already in the prompt
	PresencePenalty float64 `json:"presence_penalty,omitzero"`

	// FrequencyPenalty affects the likelihood of the model
	// repeatedly using the same words or phrases
	FrequencyPenalty float64 `json:"frequency_penalty,omitzero"`

	// StopSequences specifies sequences that will stop generation when produced.
	// Providers may have limits on the number of stop sequences.
	StopSequences []string `json:"stop_sequences,omitempty"`

	// Seed provides an integer seed for random sampling.
	// If supported by the model, calls will generate deterministic results.
	Seed int `json:"seed,omitzero"`

	// Headers specifies additional HTTP headers to send with the request.
	// Only applicable for HTTP-based providers.
	Headers http.Header `json:"headers,omitempty"`

	// Tools that are available for the model to use.
	Tools []ToolDefinition `json:"tools,omitempty"`

	// ToolChoice specifies how the model should select which tool to use.
	// Defaults to 'auto'.
	ToolChoice *ToolChoice `json:"tool_choice,omitzero"`

	// ResponseFormat specifies whether the output should be text or JSON.
	// For JSON output, a schema can optionally guide the model.
	ResponseFormat *ResponseFormat `json:"response_format,omitzero"` // TODO: Only for providers, not exposed.

	// ProviderMetadata contains additional provider-specific metadata.
	// The metadata is passed through to the provider from the AI SDK and enables
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type CallWarning struct {

	// Type indicates the kind of warning: "unsupported-setting", "unsupported-tool", or "other"
	Type string `json:"type"`

	// Setting contains the name of the unsupported setting when Type is "unsupported-setting"
	Setting string `json:"setting,omitzero"`

	// Tool contains the unsupported tool when Type is "unsupported-tool"
	Tool ToolDefinition `json:"tool,omitzero"`

	// Details provides additional information about the warning
	Details string `json:"details,omitzero"`

	// Message contains a human-readable warning message
	Message string `json:"message,omitzero"`
}

type ContentBlock interface {
	// Type returns the type of the content block.
	// Valid types are: "text", "image", "file", "tool-call", "tool-result", "reasoning".
	Type() ContentBlockType
	// ProviderMetadata returns the provider-specific metadata for the content block.
	GetProviderMetadata() *ProviderMetadata
}

type ContentBlockType string

type EmptyResponseBodyError struct {
	*AISDKError
}

type ErrorEvent struct {
	// Err contains any error messages or error objects encountered during the stream
	Err any `json:"error"`
}

type EventType string

type FileBlock struct {
	// Filename is the filename of the file. Optional.
	Filename string `json:"filename,omitzero"` // TODO: input only

	// URL is the external URL of the file.
	URL string `json:"url,omitzero"`

	// Data contains the file data as raw bytes.
	// If this is set, also set the MimeType so that the AI SDK knows
	// how to interpret the data.
	Data []byte `json:"data,omitempty"`

	// MediaType is the IANA media type (mime type) of the file.
	// It can support wildcards, e.g. `image/*` (in which case the provider needs to take appropriate action).
	// See: https://www.iana.org/assignments/media-types/media-types.xhtml
	MediaType string `json:"media_type,omitzero"`

	// ProviderMetadata contains additional provider-specific metadata.
	// They are passed through to the provider from the AI SDK and enable
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type FileEvent struct {
	// MediaType is the IANA media type (mime type) of the file
	MediaType string `json:"media_type"`
	// Data contains the generated file as a byte array
	Data []byte `json:"data"`
}

type FinishEvent struct {
	// Usage contains token usage statistics
	Usage Usage `json:"usage,omitzero"`

	// FinishReason indicates why the model stopped generating
	FinishReason FinishReason `json:"finish_reason"`

	// ProviderMetadata contains provider-specific metadata
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type FinishReason string

type FunctionTool struct {
	// Name is the unique identifier for this tool within this model call
	Name string `json:"name"`

	// Description explains the tool's purpose. The language model uses this to understand
	// the tool's purpose and provide better completion suggestions.
	Description string `json:"description,omitzero"`

	// InputSchema defines the expected inputs. The language model uses this to understand
	// the tool's input requirements and provide matching suggestions.
	// InputSchema should be defined using a JSON schema.
	InputSchema *jsonschema.Schema `json:"input_schema,omitzero"`

	// ProviderMetadata contains additional provider-specific metadata.
	// They are passed through to the provider from the AI SDK and enable
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type ImageBlock struct {
	// URL is the external URL of the image.
	URL string `json:"url,omitzero"`

	// Data contains the image data as raw bytes.
	// If this is set, also set the MimeType so that the AI SDK knows
	// how to interpret the data.
	Data []byte `json:"data,omitempty"`

	// MediaType is the IANA media type (mime type) of the image
	MediaType string `json:"media_type,omitzero"`

	// ProviderMetadata contains additional provider-specific metadata.
	// They are passed through to the provider from the AI SDK and enable
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type InvalidArgumentError struct {
	*AISDKError

	// Argument is the name of the invalid argument
	Argument string
}

type InvalidPromptError struct {
	*AISDKError

	// Prompt is the invalid prompt that caused the error
	Prompt any
}

type InvalidResponseDataError struct {
	*AISDKError

	// Data is the invalid response data that caused the error
	Data any
}

type JSONParseError struct {
	*AISDKError

	// Text is the string that failed to parse as JSON
	Text string
}

type LanguageModel interface {
	// ProviderName returns the name of the provider for logging purposes.
	ProviderName() string

	// ModelID returns the provider-specific model ID for logging purposes.
	ModelID() string

	// SupportedUrls returns URL patterns supported by the model, grouped by media type.
	//
	// The MediaType field contains media type patterns or full media types (e.g. "*/*" for everything,
	// "audio/*", "video/*", or "application/pdf"). The URLPatterns field contains arrays of regular
	// expression patterns that match URL paths.
	//
	// The matching is performed against lowercase URLs.
	//
	// URLs that match these patterns are supported natively by the model and will not
	// be downloaded by the SDK. For non-matching URLs, the SDK will download the content
	// and pass it directly to the model.
	//
	// If nil or an empty slice is returned, the SDK will download all files.
	SupportedUrls() []SupportedURL

	// Generate generates a language model output (non-streaming).
	//
	// The prompt parameter is a standardized prompt type, not the user-facing prompt.
	// The AI SDK methods will map the user-facing prompt types such as chat or
	// instruction prompts to this format.
	Generate(ctx context.Context, prompt []Message, opts CallOptions) (*Response, error)

	// Stream generates a language model output (streaming).
	// Returns a stream of events from the model.
	//
	// The prompt parameter is a standardized prompt type, not the user-facing prompt.
	// The AI SDK methods will map the user-facing prompt types such as chat or
	// instruction prompts to this format.
	Stream(ctx context.Context, prompt []Message, opts CallOptions) (*StreamResponse, error)
}

type LoadAPIKeyError struct {
	*AISDKError
}

type LoadSettingError struct {
	*AISDKError
}

type LogProb struct {
	// Token is the text of the token
	Token string `json:"token"`

	// LogProb is the log probability of the token
	LogProb float64 `json:"logprob"`

	// TopLogProbs contains the log probabilities of alternative tokens
	TopLogProbs []TokenLogProb `json:"top_logprobs"`
}

type LogProbs []LogProb

type Message interface {
	// Role returns the role of the message sender.
	// Valid roles are: "system", "user", "assistant", or "tool".
	Role() MessageRole
	GetProviderMetadata() *ProviderMetadata
}

type MessageRole string

type MetadataSource interface {
	GetProviderMetadata() *ProviderMetadata
}

type ModelType string

type NoContentGeneratedError struct {
	*AISDKError
}

type NoSuchModelError struct {
	*AISDKError

	// ModelID is the identifier of the model that was not found
	ModelID string

	// ModelType is the type of model that was requested
	ModelType ModelType
}

type ObjectGenerationMode string

type Provider interface {
	// LanguageModel returns the language model with the given id.
	// The model id is then passed to the provider function to get the model.
	//
	// Parameters:
	//   modelID: The id of the model to return.
	//
	// Returns:
	//   The language model associated with the id
	//   error of type NoSuchModelError if no such model exists
	LanguageModel(modelID string) (LanguageModel, error)
}

type ProviderDefinedTool struct {
	// ID is the tool identifier in format "<provider-name>.<tool-name>"
	ID string `json:"id"`

	// Name returns the unique name used to identify this tool within the model's messages.
	// This is the name that will be used by the language model as the value of the ToolName field
	// in ToolCall blocks.
	Name string `json:"name"`

	// Args contains the arguments for configuring the tool. Must match the expected arguments
	// defined by the provider for this tool.
	// Providers should support both a JSON-serializable type and a map[string]interface{} type.
	Args any `json:"args"`
}

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

type ReasoningBlock struct {
	// Text contains the reasoning text.
	Text string `json:"text,omitempty"`

	// Signature is an optional signature for verifying that the reasoning originated from the model.
	Signature string `json:"signature,omitzero"`

	// ProviderMetadata contains additional provider-specific metadata.
	// They are passed through to the provider from the AI SDK and enable
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type ReasoningEvent struct {
	// TextDelta is a partial reasoning text from the model
	TextDelta string `json:"text_delta"`
}

type ReasoningSignatureEvent struct {
	// Signature is the cryptographic signature for verifying reasoning
	Signature string `json:"signature"`
}

type RequestInfo struct {
	// Body is the raw HTTP body that was sent to the provider
	Body []byte `json:"body,omitempty"`
}

type Response struct {
	// Content contains the ordered list of content blocks that the model generated.
	Content []ContentBlock `json:"content"`

	// FinishReason contains an explanation for why the model finished generating.
	FinishReason FinishReason `json:"finish_reason"`

	// Usage contains information about the number of tokens used by the model.
	Usage Usage `json:"usage"`

	// Additional provider-specific metadata. They are passed through from the
	// provider to enable provider-specific functionality.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`

	// RequestInfo is optional request information for telemetry and debugging purposes.
	RequestInfo *RequestInfo `json:"request,omitzero"`

	// ResponseInfo is optional response information for telemetry and debugging purposes.
	ResponseInfo *ResponseInfo `json:"response,omitzero"`

	// Warnings is a list of warnings that occurred during the call,
	// e.g. unsupported settings.
	Warnings []CallWarning `json:"warnings,omitempty"`
}

type ResponseFormat struct {
	// Type indicates the response format type ("text" or "json")
	Type string `json:"type"`

	// Schema optionally provides a JSON schema to guide the model's output
	Schema *jsonschema.Schema `json:"schema,omitzero"`

	// Name optionally provides a name for the output to guide the model
	Name string `json:"name,omitzero"`

	// Description optionally provides additional context to guide the model
	Description string `json:"description,omitzero"`
}

type ResponseInfo struct {
	// ID for the generated response, if the provider sends one.
	ID string `json:"id,omitzero"`

	// Timestamp for the start of the generated response, if the provider sends one.
	Timestamp time.Time `json:"timestamp,omitzero"`

	// ModelID of the model that was used to generate the response, if the provider sends one.
	ModelID string `json:"model_id,omitzero"`

	// Headers contains the HTTP response headers.
	Headers http.Header `json:"headers,omitzero"`

	// Body is the raw HTTP body that was returned by the provider.
	// Not provided for streaming responses.
	Body []byte `json:"body,omitempty"`

	// Status is a status code and message. e.g. "200 OK"
	Status string `json:"status,omitzero"`

	// StatusCode is a status code as integer. e.g. 200
	StatusCode int `json:"status_code,omitzero"`
}

type ResponseMetadataEvent struct {
	// ID for the generated response, if the provider sends one
	ID string `json:"id,omitzero"`
	// Timestamp represents when the stream part was generated
	Timestamp time.Time `json:"timestamp,omitzero"`
	// ModelID for the generated response, if the provider sends one
	ModelID string `json:"model_id,omitzero"`
}

type Source struct {
	// SourceType indicates the type of source. Currently only "url" is supported.
	SourceType string `json:"source_type"`

	// ID is the unique identifier of the source.
	ID string `json:"id"`

	// URL is the URL of the source.
	URL string `json:"url"`

	// Title is the optional title of the source.
	Title string `json:"title,omitzero"`

	// ProviderMetadata contains additional provider-specific metadata.
	ProviderMetadata ProviderMetadata `json:"provider_metadata,omitzero"`
}

type SourceBlock struct {
	// ID is the ID of the source.
	ID string `json:"id"`

	// URL is the external URL of the source.
	URL string `json:"url"`

	// Title is the title of the source.
	Title string `json:"title,omitzero"`

	// ProviderMetadata contains additional provider-specific metadata.
	// They are passed through to the provider from the AI SDK and enable
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type SourceEvent struct {
	// Source contains information about the source
	Source Source `json:"source"`
}

type StreamEvent interface {
	// Type returns the type of event being received.
	Type() EventType
}

type StreamResponse struct {
	// Stream is the sequence of events received from the model.
	// Iterating over events might block if we're waiting for the LLM to respond.
	Stream iter.Seq[StreamEvent]

	// RequestInfo is optional request information for telemetry and debugging purposes.
	RequestInfo *RequestInfo `json:"request,omitzero"`

	// ResponseInfo is optional response information for telemetry and debugging purposes.
	ResponseInfo *ResponseInfo `json:"response,omitzero"`
}

type SupportedURL struct {
	// MediaType is the IANA media type (mime type) of the URL.
	// A simple '*' wildcard is supported for the mime type or subtype
	// (e.g., "application/pdf", "audio/*", "*/*").
	MediaType string

	// TODO: change reasoning to support reasoning blocks as well
	// URLPatterns contains regex patterns for URL paths that match this media type
	URLPatterns []string
}

type SystemMessage struct {
	// Content contains the message text
	Content string `json:"content"`

	// ProviderMetadata contains additional provider-specific metadata.
	// They are passed through to the provider from the AI SDK and enable
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type TextBlock struct {
	// Text contains the text content
	Text string `json:"text"`

	// ProviderMetadata contains additional provider-specific metadata.
	// They are passed through to the provider from the AI SDK and enable
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type TextDeltaEvent struct {
	// TextDelta is a partial text response from the model
	TextDelta string `json:"text_delta"`
}

type TokenLogProb struct {
	// Token is the text of the token
	Token string `json:"token"`

	// LogProb is the log probability of the token
	LogProb float64 `json:"logprob"`
}

type TooManyEmbeddingValuesForCallError struct {
	*AISDKError

	// Provider is the name of the AI provider
	Provider string

	// ModelID is the identifier of the model
	ModelID string

	// MaxEmbeddingsPerCall is the maximum number of embeddings allowed per call
	MaxEmbeddingsPerCall int

	// Values are the embedding values that were provided
	Values []any
}

type ToolCallBlock struct {

	// ToolCallID is the ID of the tool call. This ID is used to match the tool call with the tool result.
	ToolCallID string `json:"tool_call_id"`

	// ToolName is the name of the tool that is being called
	// TODO: rename to ToolID (and change implementation in each provider)
	ToolName string `json:"tool_name"`

	// Args contains the arguments of the tool call as a JSON payload matching
	// the tool's input schema.
	// Note that args are often generated by the language model and may be
	// malformed.
	Args json.RawMessage `json:"args"` // TODO: decide if this is the right type for this field

	// ProviderMetadata contains additional provider-specific metadata.
	// They are passed through to the provider from the AI SDK and enable
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type ToolCallDeltaEvent struct {
	// ToolCallID is the ID of the tool call
	ToolCallID string `json:"tool_call_id"`

	// ToolName is the name of the tool being invoked
	ToolName string `json:"tool_name"`

	// ArgsDelta is a partial JSON byte slice update for the tool call arguments
	ArgsDelta []byte `json:"args_delta"`
}

type ToolCallEvent struct {
	// ToolCallID is the ID of the tool call. This ID is used to match the tool call with the tool result.
	ToolCallID string `json:"tool_call_id"`

	// ToolName is the name of the tool being invoked.
	ToolName string `json:"tool_name"`

	// Args contains the arguments of the tool call as a JSON payload matching
	// the tool's input schema.
	// Note that args are often generated by the language model and may be
	// malformed.
	Args json.RawMessage `json:"args"`
}

type ToolChoice struct {
	// Type indicates how tools should be selected:
	// - "auto": tool selection is automatic (can be no tool)
	// - "none": no tool must be selected
	// - "required": one of the available tools must be selected
	// - "tool": a specific tool must be selected
	Type string `json:"type"`

	// ToolName specifies which tool to use when Type is "tool"
	// TODO: rename to ToolID (and change implementation)
	ToolName string `json:"tool_name,omitzero"`
}

type ToolDefinition interface {
	// Type is the type of the tool. Either "function" or "provider-defined".
	Type() string
	// contains filtered or unexported methods
}

type ToolMessage struct {
	// Content contains an array of tool results
	Content []ToolResultBlock `json:"content"`

	// ProviderMetadata contains additional provider-specific metadata.
	// They are passed through to the provider from the AI SDK and enable
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type ToolResultBlock struct {

	// ToolCallID is the ID of the tool call that this result is associated with
	ToolCallID string `json:"tool_call_id"`

	// ToolName is the ID of the tool that generated this result
	// TODO: rename to ToolID
	ToolName string `json:"tool_name"`

	// Result contains the result of the tool call. This is a JSON-serializable object.
	Result any `json:"result"`

	// IsError indicates if the result is an error or an error message
	IsError bool `json:"is_error,omitzero"`

	// Content contains tool results as an array of blocks.
	// This enables advanced tool results including images.
	// When this is used, the Result field should be ignored
	// (if the provider supports content).
	Content []ContentBlock `json:"content,omitempty"`

	// ProviderMetadata contains additional provider-specific metadata.
	// They are passed through to the provider from the AI SDK and enable
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}

type TypeValidationError struct {
	*AISDKError

	// Value is the value that failed validation
	Value any
}

type UnsupportedFunctionalityError struct {
	*AISDKError

	// Functionality is the name of the unsupported functionality
	Functionality string
}

type Usage struct {
	// InputTokens is the number of tokens used by the input (prompt).
	InputTokens int `json:"input_tokens"`

	// OutputTokens is the number of tokens in the generated output (completion or tool call).
	OutputTokens int `json:"output_tokens"`

	// TotalTokens is the total number of tokens used as reported by the provider.
	// Note that this might be different from the sum of input tokens and output tokens
	// because it might include reasoning tokens or other overhead.
	TotalTokens int `json:"total_tokens"`

	// ReasoningTokens is the number of tokens used by model as part of the reasoning process.
	ReasoningTokens int `json:"reasoning_tokens,omitzero"`

	// CachedInputTokens is the number of input tokens that were cached from a previous call.
	CachedInputTokens int `json:"cached_input_tokens,omitzero"`
}

type UserMessage struct {
	// Content contains an array of content blocks (text, image, or file)
	Content []ContentBlock `json:"content"`

	// ProviderMetadata contains additional provider-specific metadata.
	// They are passed through to the provider from the AI SDK and enable
	// provider-specific functionality that can be fully encapsulated in the provider.
	ProviderMetadata *ProviderMetadata `json:"provider_metadata,omitzero"`
}