provider

type CapableModel interface {
	Capabilities() ModelCapabilities
}

type EmbedParams struct {
	// ProviderOptions are provider-specific request parameters.
	ProviderOptions map[string]any
}

type EmbedResult struct {
	// Embeddings contains the generated vectors.
	Embeddings [][]float64

	// Usage tracks token consumption.
	Usage Usage

	// ProviderMetadata contains provider-specific response data.
	ProviderMetadata map[string]map[string]any

	// Response contains provider-specific response metadata (ID, model, headers).
	Response ResponseMetadata
}

type EmbeddingModel interface {
	// ModelID returns the provider-specific model identifier.
	ModelID() string

	// DoEmbed generates embeddings for the given values.
	DoEmbed(ctx context.Context, values []string, params EmbedParams) (*EmbedResult, error)

	// MaxValuesPerCall returns the maximum number of values that can be embedded in a single call.
	// Returns 0 if there is no limit.
	MaxValuesPerCall() int
}

type FileUpload struct {
	// Reader is the file content to upload.
	Reader io.Reader
	// Filename is the name of the file.
	Filename string
	// MediaType is the MIME type of the file (e.g. "application/pdf").
	MediaType string
	// Purpose describes the intended use (e.g. "assistants", "vision").
	Purpose string
}

type FileUploadCapableModel interface {
	FileUploader() FileUploader
}

type FileUploader interface {
	// UploadFile uploads a file and returns a reference to the remote file.
	UploadFile(ctx context.Context, upload FileUpload) (*RemoteFileRef, error)
	// DeleteFile deletes a previously uploaded remote file.
	DeleteFile(ctx context.Context, ref RemoteFileRef) error
}

type FinishReason string

type GenerateParams struct {
	// Messages is the conversation history.
	Messages []Message

	// System is the system prompt.
	System string

	// Tools available to the model.
	Tools []ToolDefinition

	// MaxOutputTokens limits the response length. 0 means provider default.
	MaxOutputTokens int

	// Temperature controls randomness. nil means provider default.
	Temperature *float64

	// TopP controls nucleus sampling. nil means provider default.
	TopP *float64

	// TopK limits sampling to the top K tokens. nil means provider default.
	TopK *int

	// FrequencyPenalty penalizes tokens based on frequency. nil means provider default.
	FrequencyPenalty *float64

	// PresencePenalty penalizes tokens that have appeared. nil means provider default.
	PresencePenalty *float64

	// Seed for deterministic generation. nil means provider default.
	Seed *int

	// StopSequences causes generation to stop when encountered.
	StopSequences []string

	// Headers are additional HTTP headers for this request.
	Headers map[string]string

	// ProviderOptions are provider-specific request parameters.
	ProviderOptions map[string]any

	// PromptCaching enables provider-specific prompt caching.
	PromptCaching bool

	// ToolChoice controls tool selection: "auto", "none", "required", or a specific tool name.
	ToolChoice string

	// ResponseFormat requests structured JSON output matching a schema.
	// When set, providers apply their native JSON mode (OpenAI json_schema,
	// Anthropic tool trick, Gemini responseMimeType+responseSchema).
	ResponseFormat *ResponseFormat
}

type GenerateResult struct {
	// Text is the generated text content.
	Text string

	// Reasoning is the model's thinking/reasoning text (when extended
	// thinking is enabled). Excludes signatures and redacted blocks —
	// those remain in ProviderMetadata for replay. Empty when the
	// provider does not return reasoning or thinking is disabled.
	Reasoning string

	// ToolCalls requested by the model.
	ToolCalls []ToolCall

	// Sources extracted from response annotations (e.g. url_citation).
	Sources []Source

	// FinishReason indicates why generation stopped.
	FinishReason FinishReason

	// Usage tracks token consumption.
	Usage Usage

	// Response contains provider-specific metadata.
	Response ResponseMetadata

	// ProviderMetadata contains provider-specific response data
	// (e.g. logprobs, prediction tokens).
	ProviderMetadata map[string]map[string]any
}

type ImageData struct {
	// Data is the raw image bytes.
	Data []byte

	// MediaType (e.g. "image/png").
	MediaType string
}

type ImageModel interface {
	// ModelID returns the provider-specific model identifier.
	ModelID() string

	// DoGenerate generates images from the given parameters.
	DoGenerate(ctx context.Context, params ImageParams) (*ImageResult, error)
}

type ImageParams struct {
	// Prompt describes the image to generate.
	Prompt string

	// N is the number of images to generate.
	N int

	// Size specifies dimensions (e.g. "1024x1024").
	Size string

	// AspectRatio (e.g. "16:9", "1:1"). Alternative to Size.
	AspectRatio string

	// ProviderOptions are provider-specific parameters.
	ProviderOptions map[string]any
}

type ImageResult struct {
	Images []ImageData

	// ProviderMetadata contains provider-specific response data
	// (e.g. revisedPrompt).
	ProviderMetadata map[string]map[string]any

	// Usage tracks token or operation consumption (if reported by the provider).
	Usage Usage

	// Response contains provider-specific response metadata (ID, model, headers).
	Response ResponseMetadata
}

type InvalidatingTokenSource interface {
	TokenSource
	Invalidate()
}

type LanguageModel interface {
	// ModelID returns the provider-specific model identifier (e.g. "gpt-4o", "claude-sonnet-4-20250514").
	ModelID() string

	// DoGenerate performs a non-streaming generation request.
	DoGenerate(ctx context.Context, params GenerateParams) (*GenerateResult, error)

	// DoStream performs a streaming generation request.
	DoStream(ctx context.Context, params GenerateParams) (*StreamResult, error)
}

type Message struct {
	// Role identifies the sender.
	Role Role

	// Content parts that make up this message.
	Content []Part

	// ProviderOptions are provider-specific message parameters.
	ProviderOptions map[string]any
}

type ModalitySet struct {
	Text  bool
	Audio bool
	Image bool
	Video bool
	PDF   bool
}

type ModelCapabilities struct {
	// Temperature indicates the model accepts a temperature parameter.
	Temperature bool

	// Reasoning indicates the model supports extended thinking/reasoning.
	Reasoning bool

	// Attachment indicates the model supports file attachments.
	Attachment bool

	// ToolCall indicates the model supports tool/function calling.
	ToolCall bool

	// FileUpload indicates the model supports remote file upload.
	FileUpload bool

	// InputModalities lists supported input types.
	InputModalities ModalitySet

	// OutputModalities lists supported output types.
	OutputModalities ModalitySet
}

type Part struct {
	// Type identifies this part's kind.
	Type PartType

	// Text content (for PartText and PartReasoning).
	Text string

	// URL for images (data:image/png;base64,... format).
	URL string

	// Tool call fields (for PartToolCall and PartToolResult).
	ToolCallID string
	ToolName   string
	ToolInput  json.RawMessage

	// ToolOutput is the result text (for PartToolResult).
	ToolOutput string

	// CacheControl directive (e.g. "ephemeral") for prompt caching.
	CacheControl string

	// Detail level for image parts ("low", "high", "auto").
	Detail string

	// MediaType of the content (for PartImage, PartFile).
	MediaType string

	// Filename of the content (for PartFile).
	Filename string

	// RemoteRef is a reference to an uploaded remote file (for PartFile, PartImage).
	// When set, the provider uses the remote reference instead of inline data.
	RemoteRef *RemoteFileRef

	// ProviderOptions are provider-specific part parameters.
	ProviderOptions map[string]any
}

type PartType string

type RemoteFileRef struct {
	// Provider identifies which provider owns this file.
	Provider string
	// ID is the provider-specific file identifier.
	ID string
	// URI is the provider-specific file URI (e.g. for Gemini).
	URI string
	// Filename is the original file name.
	Filename string
	// MediaType is the MIME type of the file.
	MediaType string
	// ExpiresAt is when the remote file expires (zero if unknown).
	ExpiresAt time.Time
	// Data holds the raw file bytes for fallback on providers without native file APIs.
	Data []byte
}

type ResponseFormat struct {
	// Name identifies the schema (used by OpenAI's json_schema mode).
	Name string

	// Schema is the JSON Schema that the output must conform to.
	Schema json.RawMessage
}

type ResponseMetadata struct {
	// ID is the provider's response identifier.
	ID string

	// Model is the actual model used (may differ from requested).
	Model string

	// Headers are selected response headers.
	Headers map[string]string

	// ProviderMetadata contains provider-specific metadata (e.g. iterations,
	// context_management, container, citations, reasoning signatures).
	ProviderMetadata map[string]any
}

type Role string

type Source struct {
	// ID is the source identifier (provider-assigned or generated).
	ID string

	// Type identifies the source kind (e.g. "url", "document").
	// Maps to Vercel's sourceType field.
	Type string

	// URL is the citation URL.
	URL string

	// Title is the citation title.
	Title string

	// StartIndex is the start character offset in the text.
	StartIndex int

	// EndIndex is the end character offset in the text.
	EndIndex int

	// ProviderMetadata contains provider-specific source data.
	ProviderMetadata map[string]any
}

type StopCause string

type StreamChunk struct {
	// Type identifies this chunk's kind.
	Type StreamChunkType

	// Text content (for ChunkText and ChunkReasoning).
	Text string

	// Tool call fields (for ChunkToolCall and ChunkToolCallStreamStart).
	ToolCallID string
	ToolName   string
	ToolInput  string

	// FinishReason (for ChunkStepFinish and ChunkFinish).
	FinishReason FinishReason

	// Usage (for ChunkFinish, may also appear on ChunkStepFinish).
	Usage Usage

	// Error carries the provider/goai error when Type == ChunkError.
	//   - Nil for all non-ChunkError chunk types.
	//   - May wrap APIError, NetworkError, or plain errors produced by the
	//     provider or goai's tool loop (e.g. tool execution failures that are
	//     surfaced as chunks rather than returned via Err()).
	//   - Providers set this field directly; consumers should use
	//     errors.Is / errors.As to branch on specific error categories rather
	//     than comparing error values.
	Error error

	// Response metadata (populated on ChunkFinish with ID, Model from the provider).
	Response ResponseMetadata

	// Metadata for provider-specific data (e.g. thoughtSignature).
	Metadata map[string]any

	// StoppedBy classifies how the tool loop terminated. Only meaningful on
	// the final ChunkFinish emitted by goai's tool loop. Values:
	//
	//	""                     - single-step provider chunk or unknown
	//	"natural"              - the loop ended because the model did not request
	//	                         additional tool calls (FinishStop or equivalent)
	//	"max-steps"            - MaxSteps was reached while tool calls were still
	//	                         pending (StepsExhausted)
	//	"predicate"            - WithStopWhen predicate returned true
	//	"before-step"          - OnBeforeStep hook returned Stop=true
	//	"abort"                - the stream terminated on an error path
	//	"empty"                - provider closed its stream with no chunks
	//	                         (streaming-only; see StopCauseEmpty godoc)
	//	"no-executable-tools"  - model returned tool calls but no tool in the
	//	                         configured set has an Execute function
	//	                         (sync-only; see StopCauseNoExecutableTools godoc)
	StoppedBy StopCause
}

type StreamChunkType string

type StreamResult struct {
	// Stream emits chunks as they arrive. The channel is closed when the stream ends.
	Stream <-chan StreamChunk
}

type Token struct {
	// Value is the token string (API key, OAuth access token, etc.).
	Value string

	// ExpiresAt is when the token expires. Zero value means no expiry.
	ExpiresAt time.Time
}

type TokenFetchFunc func(ctx context.Context) (*Token, error)

type TokenSource interface {
	// Token returns a valid token. Implementations must be safe for concurrent use.
	Token(ctx context.Context) (string, error)
}

type ToolCall struct {
	// ID is a unique identifier for this tool call.
	ID string

	// Name of the tool to invoke.
	Name string

	// Input is the JSON-encoded arguments.
	Input json.RawMessage

	// Metadata carries provider-specific data that must be preserved across
	// tool round-trips (e.g., Google's thoughtSignature).
	Metadata map[string]any
}

type ToolDefinition struct {
	// Name is the tool's identifier.
	Name string

	// Description explains what the tool does (used by the model to decide when to call it).
	Description string

	// InputSchema is the JSON Schema for the tool's input parameters.
	InputSchema json.RawMessage

	// ProviderDefinedType, when non-empty, marks this as a provider-defined tool
	// (e.g. "computer_20250124", "bash_20250124", "text_editor_20250124").
	// Providers use this to emit the correct API type instead of "custom".
	ProviderDefinedType string

	// ProviderDefinedOptions holds provider-specific tool configuration
	// (e.g. displayWidthPx for computer use). Providers interpret these as needed.
	ProviderDefinedOptions map[string]any
}

type ToolResult struct {
	// ToolCallID matches the ID of the originating ToolCall.
	ToolCallID string

	// ToolName is the name of the tool that was invoked.
	ToolName string

	// Output is the stringified result sent to the model. For failed calls
	// this is "error: <message>" (matching what the tool-result message
	// carries); predicates should inspect Error or IsError to distinguish
	// errors from deliberately empty successful outputs.
	Output string

	// Error is the error returned by the tool's Execute function, or
	// goai.ErrUnknownTool when the model requested a tool not in the
	// configured set. Nil on success.
	//
	// The standard encoding/json package cannot marshal the error
	// interface directly (it would emit "{}"). ToolResult implements
	// MarshalJSON to surface Error as a string ("Error.Error()") in
	// JSON output so the field is useful in observability / logging.
	Error error

	// IsError is a convenience boolean equivalent to Error != nil.
	IsError bool
}

type Usage struct {
	InputTokens      int
	OutputTokens     int
	TotalTokens      int
	ReasoningTokens  int
	CacheReadTokens  int
	CacheWriteTokens int
}