provider

type APIError struct {
	Provider string
	Status   int
	Body     string
}

type AuthError struct {
	Provider string // the provider instance name, e.g. "openai"
	KeyEnv   string // the api_key_env the key is read from, when known
	Status   int    // the HTTP status (401 or 403)
	HasKey   bool   // a non-empty key was sent vs. no key configured
}

type BudgetStatus struct {
	RPM         int `json:"rpm"`
	Used        int `json:"used"`
	Remaining   int `json:"remaining"`
	ReserveMain int `json:"reserveMain"`
	WindowSecs  int `json:"windowSecs"` // seconds until the window resets
}

type Chunk struct {
	Type      ChunkType
	Text      string    // ChunkText, ChunkReasoning
	Signature string    // ChunkReasoning: opaque proof for the reasoning (Anthropic thinking signature), when issued
	ToolCall  *ToolCall // ChunkToolCallStart (ID+Name only), ChunkToolCall (complete)
	Usage     *Usage    // ChunkUsage
	Err       error     // ChunkError
}

type ChunkType int

type Config struct {
	Name    string         // instance name, e.g. "openai"
	BaseURL string         // OpenAI-compatible endpoint
	Model   string         // model id
	APIKey  string         // resolved from api_key_env
	Extra   map[string]any // kind-specific options
}

type ContentPart struct {
	Type     string    `json:"type"`                // "text" or "image_url"
	Text     string    `json:"text,omitempty"`      // for Type == "text"
	ImageURL *ImageURL `json:"image_url,omitempty"` // for Type == "image_url"
}

type Factory func(cfg Config) (Provider, error)

type ImageURL struct {
	URL    string `json:"url"`              // "data:image/png;base64,..."
	Detail string `json:"detail,omitempty"` // "low", "high", "auto"
}

type Message struct {
	Role             Role   `json:"role"`
	Content          any    `json:"content,omitempty"`           // string or []ContentPart (multimodal)
	ReasoningContent string `json:"reasoning_content,omitempty"` // assistant: thinking-mode chain-of-thought, round-tripped on multi-turn
	// ReasoningSignature is an opaque, provider-issued proof that ReasoningContent
	// is genuine model output. Anthropic requires the signed thinking block be
	// replayed on the next turn when a tool call followed thinking; providers
	// without signed reasoning (e.g. the openai-compatible ones) leave it empty.
	// Round-tripped alongside ReasoningContent.
	ReasoningSignature string     `json:"reasoning_signature,omitempty"`
	ToolCalls          []ToolCall `json:"tool_calls,omitempty"`   // set by assistant
	ToolCallID         string     `json:"tool_call_id,omitempty"` // links a tool result to its call
	Name               string     `json:"name,omitempty"`         // tool message: tool name
}

type Pricing struct {
	CacheHit float64 `toml:"cache_hit"` // per 1M cached prompt tokens
	Input    float64 `toml:"input"`     // per 1M uncached prompt tokens
	Output   float64 `toml:"output"`    // per 1M completion tokens
	Currency string  `toml:"currency"`
}

type Provider interface {
	// Name returns the provider instance name, e.g. "openai" / "anthropic".
	Name() string
	// Stream starts a streaming completion, pushing increments on the channel.
	// Cancelling ctx must abort the underlying request; a closed channel marks
	// the end of the completion.
	Stream(ctx context.Context, req Request) (<-chan Chunk, error)
}

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

type Request struct {
	Messages    []Message
	Tools       []ToolSchema
	Temperature float64
	MaxTokens   int
}

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

type RetryInfo struct {
	Attempt int
	Max     int
	Delay   time.Duration
	Err     error
}

type RetryNotify func(RetryInfo)

type Role string

type SendOptions struct {
	ProvName   string // provider instance name for error messages
	KeyEnv     string // api_key_env for AuthError
	KeyPresent bool   // a non-empty key was configured
	RetryAuth  bool   // retry 401/403 up to maxAuthRetries (key previously worked)
}

type StreamInterruptedError struct {
	Err error
}

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

type ToolSchema struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Parameters  json.RawMessage `json:"parameters"`
}

type Usage struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
	CacheHitTokens   int    // prompt tokens served from cache
	CacheMissTokens  int    // prompt tokens not cached
	ReasoningTokens  int    // subset of CompletionTokens spent on chain-of-thought
	FinishReason     string // "stop", "tool_calls", "length", "content_filter", "repetition_truncation", …
}