llm

type ChatMessage struct {
	Role       string     `json:"role"`
	Content    string     `json:"content,omitempty"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
	Name       string     `json:"name,omitempty"`
}

type ChatRequest struct {
	Model       string           `json:"model"`
	Messages    []ChatMessage    `json:"messages"`
	Tools       []ToolDefinition `json:"tools,omitempty"`
	Temperature *float64         `json:"temperature,omitempty"`
	MaxTokens   int              `json:"max_tokens,omitempty"`
	Stream      bool             `json:"stream,omitempty"`
}

type ChatResponse struct {
	ID           string      `json:"id"`
	Message      ChatMessage `json:"message"`
	Usage        UsageInfo   `json:"usage"`
	FinishReason string      `json:"finish_reason"`
	// Endpoint is the URL the client POSTed to (base URL + provider path).
	// Set by the provider client so the llm_call audit event can record the
	// invoked path even when payload capture is off. Internal only (json:"-").
	Endpoint string `json:"-"`
}

type Client interface {
	// Chat sends a chat completion request and returns the response.
	Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error)
	// ChatStream sends a streaming chat request and returns a channel of deltas.
	ChatStream(ctx context.Context, req *ChatRequest) (<-chan StreamDelta, error)
	// ModelID returns the model identifier this client is configured for.
	ModelID() string
}

type ClientConfig struct {
	APIKey      string
	BaseURL     string
	Model       string
	OrgID       string
	MaxRetries  int
	TimeoutSecs int

	// AuthScheme + AWSRegion control outbound authentication when
	// the operator points the client at AWS Bedrock (Anthropic
	// passthrough or OpenAI compatibility endpoint) or any other
	// SigV4-fronted gateway. Issue #202 Phase 2. Mirrors the
	// matching forge.yaml ModelRef fields.
	//
	// AuthScheme == "" preserves the pre-#202 behavior — the
	// Anthropic client sets `x-api-key: <APIKey>`, the OpenAI
	// client sets `Authorization: Bearer <APIKey>`. AuthScheme ==
	// "aws_sigv4" wraps the client's transport with the SigV4
	// signer and skips the native header logic; APIKey is ignored.
	// AuthScheme == "apikey_header" ADDITIONALLY sends APIKey in the
	// AuthHeaderName header (default "apikey") alongside the native
	// header, for gateways like Kong that read a fixed key header
	// (issue #302). AuthScheme == "apikey_header_only" sends APIKey in the
	// gateway header but SUPPRESSES the native header, for gateways that
	// inject the real upstream credential themselves.
	AuthScheme string
	AWSRegion  string

	// AuthHeaderName overrides the header used by the "apikey_header"
	// scheme. Empty → DefaultAPIKeyHeaderName ("apikey"). Ignored for
	// every other scheme. Set it for a gateway with custom key_names,
	// e.g. "x-gateway-key". Issue #302.
	AuthHeaderName string

	// PromptCaching opts the provider client into injecting the
	// provider's prompt-cache primitives on every request:
	//
	//   - anthropic: a cache_control ephemeral breakpoint on the last
	//     tool definition and on the system prompt block, caching the
	//     stable tools+system prefix across turns. Also honored by
	//     Anthropic-on-Bedrock gateways (aws_sigv4), which speak the
	//     same wire format.
	//   - openai: a stable prompt_cache_key derived from
	//     (model, system, tool names), pinning cache routing for the
	//     session. OpenAI prefix caching itself is automatic ≥1024
	//     tokens; the key improves hit locality.
	//
	// Off by default — wire formats stay byte-identical to the
	// pre-compression contract unless the operator opts in
	// (compression.cache_hints / compression.enabled in forge.yaml).
	PromptCaching bool

	// DisableStore sends `store: false` on OpenAI Responses API requests
	// (the "openai-responses" provider), telling OpenAI not to retain the
	// response server-side (~30-day default retention). Only the Responses
	// client honors it; other clients ignore it. Empty/false leaves `store`
	// unset so the API applies its own default (#383). The ChatGPT OAuth
	// path forces this true regardless (Codex backend requires it).
	DisableStore bool
}

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

type Embedder interface {
	// Embed produces embeddings for the given texts.
	Embed(ctx context.Context, req *EmbeddingRequest) (*EmbeddingResponse, error)
	// Dimensions returns the dimensionality of the embedding vectors.
	Dimensions() int
}

type EmbeddingRequest struct {
	Texts []string // texts to embed
	Model string   // optional model override
}

type EmbeddingResponse struct {
	Embeddings [][]float32
	Model      string
	Usage      UsageInfo
}

type FailoverError struct {
	Reason   FailoverReason
	Provider string
	Model    string
	Status   int
	Wrapped  error
}

type FailoverReason string

type FallbackCandidate struct {
	Provider string
	Model    string
	Client   Client
}

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

type FallbackExhaustedError struct {
	Errors []*FailoverError
}

type FunctionCall struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"` // JSON string
}

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

type StreamDelta struct {
	Content      string     `json:"content,omitempty"`
	ToolCalls    []ToolCall `json:"tool_calls,omitempty"`
	FinishReason string     `json:"finish_reason,omitempty"`
	Done         bool       `json:"done,omitempty"`
	Usage        *UsageInfo `json:"usage,omitempty"`
}

type ToolCall struct {
	ID       string       `json:"id"`
	Type     string       `json:"type"` // always "function"
	Function FunctionCall `json:"function"`
}

type ToolDefinition struct {
	Type     string         `json:"type"` // always "function"
	Function FunctionSchema `json:"function"`
}

type UsageInfo struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
	TotalTokens  int `json:"total_tokens"`
}