llm

type AmbiguousModelError struct {
	Model   string
	Targets []string
}

type ChatResponse struct {
	Model     string
	CreatedAt time.Time
	Message   Message
	Done      bool

	// UpstreamRequestID is the provider-side request identifier when the
	// provider exposes one (e.g. Anthropic's `x-request-id` response
	// header). Empty when the provider does not return one. Captured
	// for support escalation, billing reconciliation, and correlating
	// our local r_* request IDs to upstream invoice line items.
	UpstreamRequestID string

	// StopReason is the provider-side termination signal in
	// provider-neutral form. Anthropic emits "end_turn", "tool_use",
	// "max_tokens", "stop_sequence", or "pause_turn" (the latter is
	// the server-side context-pressure signal that warrants operator
	// attention). Empty when the provider doesn't expose one or the
	// stream ended unexpectedly.
	StopReason string

	// Token usage (provider-neutral)
	InputTokens              int
	OutputTokens             int
	CacheCreationInputTokens int
	CacheReadInputTokens     int
	// Per-TTL breakdown of cache-write tokens. Populated by providers
	// that return a structured cache_creation breakdown (Anthropic).
	// Zero when the provider doesn't expose the breakdown, in which
	// case callers should fall back to CacheCreationInputTokens and
	// treat the TTL mix as unknown (typically charged at the 5m rate
	// for cost estimation, since that's the default).
	CacheCreation5mInputTokens int
	CacheCreation1hInputTokens int

	// Timing (populated when available)
	TotalDuration time.Duration
	LoadDuration  time.Duration
	EvalDuration  time.Duration
}

type Client interface {
	// Chat sends a chat completion request and returns the response.
	Chat(ctx context.Context, model string, messages []Message, tools []map[string]any) (*ChatResponse, error)

	// ChatStream sends a streaming chat request. If callback is non-nil, tokens are streamed to it.
	ChatStream(ctx context.Context, model string, messages []Message, tools []map[string]any, callback StreamCallback) (*ChatResponse, error)

	// Ping checks if the provider is reachable.
	Ping(ctx context.Context) error
}

type ContextRenderStyle string

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

type ImageContent struct {
	Data      string // base64-encoded image data (no data URI prefix)
	MediaType string // MIME type: "image/jpeg", "image/png", etc.
}

type Message struct {
	Role       string          `json:"role"`
	Content    string          `json:"content"`
	Images     []ImageContent  `json:"-"` // multimodal images; marshaled per-provider
	Sections   []PromptSection `json:"-"` // system-prompt sections; provider-specific
	ToolCalls  []ToolCall      `json:"tool_calls,omitempty"`
	ToolCallID string          `json:"tool_call_id,omitempty"` // For tool responses
}

type ModelInteractionProfile struct {
	Name            string
	ContextStyle    ContextRenderStyle
	ToolCallStyle   ToolCallStyle
	TextToolProfile ToolCallTextProfile
}

type ModelProfileInput struct {
	Provider          string
	Model             string
	Family            string
	Families          []string
	TrainedForToolUse bool
}

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

type PromptSection struct {
	Name     string
	Content  string
	CacheTTL string // optional provider hint, for example "1h" or "5m"
}

type ReadyWatcher interface {
	IsReady() bool
}

type StreamCallback func(event StreamEvent)

type StreamEvent struct {
	Kind StreamEventKind

	// Token is set for KindToken events.
	Token string

	// ToolCall is set for KindToolCallStart events.
	ToolCall *ToolCall

	// ToolName and ToolResult are set for KindToolCallDone events.
	ToolName   string
	ToolResult string
	ToolError  string

	// Response is set for KindDone events (final summary).
	Response *ChatResponse

	// Data carries optional extensible metadata for events that need
	// more than the typed fields above. Used by KindLLMStart to
	// forward router decisions and context estimates.
	Data map[string]any
}

type StreamEventKind int

type ToolCall struct {
	ID       string `json:"id,omitempty"` // Provider-assigned ID (required by Anthropic for tool_result correlation)
	Function struct {
		Name      string         `json:"name"`
		Arguments map[string]any `json:"arguments"`
	} `json:"function"`
}

type ToolCallStyle string

type ToolCallTextProfile struct {
	AcceptTaggedToolCalls    bool
	AcceptMarkdownFences     bool
	AcceptConcatenatedJSON   bool
	AcceptToolNameJSONArgs   bool
	SuppressHallucinatedText bool
}