provider

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

type CacheStyle string

type CacheUsage struct {
	Reported          bool
	Style             CacheStyle
	InputTokens       int
	CachedInputTokens int
	CacheWriteTokens  int
}

type CompatOptions struct {
	Name         string
	BaseURL      string
	APIKey       string
	HTTPReferer  string
	XTitle       string
	ExtraHeaders map[string]string
	ExtraBody    map[string]any
	ErrorParser  func(statusCode int, body []byte) error
	// NonRetryable classifies an error response as permanent so the transport
	// stops retrying it. It is consulted only for statuses the shared policy
	// already considers retryable, and nil keeps that policy unchanged.
	NonRetryable func(statusCode int, body []byte) bool
	// CacheUsageEnabled gates capture of provider-reported prompt-cache usage
	// accounting into Response.CacheUsage. It never changes the outgoing
	// request.
	CacheUsageEnabled bool
	// CacheMarkersEnabled requests explicit cache_control markers on the
	// stable prefix. Default false. The openrouter factory enables it when
	// [provider] prompt_cache != "off"; implicit-cache providers leave it
	// off so their bodies stay byte-identical.
	CacheMarkersEnabled bool
	// Reasoning is this provider's default reasoning wire dialect, used when a
	// request carries a level but names no dialect of its own. Empty means the
	// provider has no vetted default and an unqualified level sends nothing.
	Reasoning reasoning.Dialect
	// RequiresReasoningReplay reports whether this provider's wire dialect
	// requires the assistant reasoning_content to be echoed back verbatim on
	// subsequent tool-call turns (DeepSeek thinking mode, z.ai preserved
	// thinking). Default false: the field is never emitted, so existing request
	// bodies are byte-identical.
	RequiresReasoningReplay bool
	// ReplayReasoningField is the replay wire field; empty = "reasoning_content".
	ReplayReasoningField string
	// RejectReasoningLessToolTurns is the documented-400 DROP gate (DeepSeek
	// ONLY). When true, assistant tool-call turns with empty ReasoningContent
	// are dropped with their tool results at emit. Independent of
	// RequiresReasoningReplay: z.ai sets replay without this bit so a
	// reasoning=off multi-step tool run still ships those turns.
	RejectReasoningLessToolTurns bool
	// ContextAccounting declares how this provider's server bills prompt
	// context (see ContextAccountingProfile). The zero value is the
	// conservative "bill everything" default, so a factory that leaves this
	// unset behaves exactly as before the field existed.
	ContextAccounting ContextAccountingProfile
	// SendSessionUserKey opts into emitting a hashed session-stickiness key
	// as the wire "user" field (see OpenAICompat.sendSessionUserKey). Only
	// the openrouter and llmgateway factories set this true.
	SendSessionUserKey bool
	// DialContext pins every dial for keyless loopback clients; nil keeps http.DefaultTransport.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
}

type Completer interface {
	Name() string
	ChatStream(ctx context.Context, req Request, w io.Writer) (string, error)
	Chat(ctx context.Context, req Request) (string, error)
	// ChatTurn is a non-stream turn that may return tool_calls.
	ChatTurn(ctx context.Context, req Request) (*Response, error)
}

type ContextAccountingAware interface {
	ContextAccounting() ContextAccountingProfile
}

type ContextAccountingProfile struct {
	// ReasoningBilling selects how historical assistant ReasoningContent is
	// charged. See ReasoningBilling's constants.
	ReasoningBilling ReasoningBilling
}

type Message 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"`
	// ReasoningContent is the model's chain-of-thought for this turn, preserved
	// verbatim on the assistant message so providers whose thinking mode requires
	// replay (DeepSeek v4, z.ai preserved thinking) can get it back on subsequent
	// tool-call turns. Empty for non-reasoning models and for non-assistant roles.
	// Persisted in session history; only ever re-emitted on the wire by providers
	// that declare the replay capability (CompatOptions.RequiresReasoningReplay).
	// Counted by the token estimators so prompt budgets see it.
	ReasoningContent string `json:"reasoning_content,omitempty"`
	// CreatedAt is local wall time when the message entered session history.
	// Persisted in session JSONL; stripped before provider API requests.
	// Zero means unknown (legacy sessions).
	CreatedAt time.Time `json:"created_at,omitempty"`
}

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

type Options struct {
	Name        string
	BaseURL     string
	APIKey      string
	Model       string
	HTTPReferer string
	XTitle      string
	// CacheUsageEnabled gates capture of provider-reported prompt-cache usage
	// accounting. It never changes what is sent to the provider.
	CacheUsageEnabled bool
	// CacheMarkersEnabled requests explicit cache_control markers on the
	// stable prefix for providers whose upstream honors them (OpenRouter
	// forwards them to Anthropic-family models; models without explicit
	// caching ignore the marker). Factories for providers that only cache
	// implicitly (deepseek, zai, ollama) ignore this option so their request
	// bodies stay byte-identical.
	CacheMarkersEnabled bool
	// ContextWindowTokens is the configured model's declared context capacity
	// (config.ModelSpec.ContextWindowTokens for the resolved model name), or 0
	// if the model is unrecognized. Only consumed by providers whose server
	// does not infer context length from the model name on its own (ollama's
	// num_ctx); other factories ignore it.
	ContextWindowTokens int
	// ReasoningDialect is the resolved model's effective wire dialect
	// (config.ModelSpec.ReasoningDialect for the resolved model name, falling
	// back to the provider's own vetted default when the model entry sets
	// none - see reasoningDialectFor). Only a factory whose provider serves a
	// caller-chosen, heterogeneous model set needs this: a single-vendor
	// factory (deepseek, zai) already knows its own dialect and ignores this
	// field. llmgateway reads it to decide, per model, whether the upstream
	// speaks a DeepSeek-style thinking dialect that requires the matching
	// reasoning-replay and reasoning-less-tool-turn-reject wire contract.
	ReasoningDialect reasoning.Dialect
	// AnthropicNativeModels lists the names, among this provider's declared
	// model catalog, whose resolved reasoning dialect is
	// reasoning.DialectAnthropicAdaptive - i.e. every model entry that
	// explicitly sets reasoning_dialect = "anthropic_adaptive" (this is never
	// a provider default outside "anthropic" itself; see
	// reasoning.CanCarryDialect, which config validation already uses to
	// reject the dialect on any provider not in its allow-list). Only
	// llmproxycli's factory reads this: it builds a per-model dispatcher
	// (llmProxyDispatchCompleter) that routes these specific models through a
	// native Anthropic Messages API completer, reusing this provider's own
	// BaseURL/APIKey, while every other model keeps going through
	// OpenAICompat unchanged. Every other factory ignores this field, the
	// same way llmgateway is the only reader of ReasoningDialect today.
	AnthropicNativeModels []string
	// DialContext, when set, replaces the transport's default dial. Set only
	// by NewForProvider, only when BaseURL resolved as a verified loopback
	// address (config.IsOllamaLoopback) - see its own call site for why. A
	// factory that builds its own pinned DialContext internally (ollama.go)
	// ignores this field; every other builtin factory forwards it verbatim
	// into CompatOptions.DialContext.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
}

type ReasoningBilling int

type ReasoningPolicy struct {
	// RequiresReplay reports whether this client's dialect requires assistant
	// reasoning_content to be echoed back verbatim on later tool-call turns.
	RequiresReplay bool
	// RejectReasoningLess reports whether this client's provider 400s on a
	// tools-carrying request that includes a reasoning-less tool-call turn
	// (see RepairReasoningLessToolExchanges).
	RejectReasoningLess bool
}

type ReasoningPolicyAware interface {
	ReasoningPolicy() ReasoningPolicy
}

type Request struct {
	Model       string
	Messages    []Message
	Temperature *float64
	MaxTokens   *int
	Stream      bool
	// StreamWriter receives content deltas when ChatTurn streams (Stream=true).
	// Tool-call argument fragments are not written here - only assistant text.
	StreamWriter io.Writer
	Tools        []ToolSpec
	ToolChoice   string // "auto", "none", or empty
	Timeout      time.Duration
	// DisableProviderReplay prevents transport and protocol fallbacks from
	// issuing a second provider request for this logical attempt.
	DisableProviderReplay bool
	// ReasoningLevel is the selected model's reasoning dial. Empty sends no
	// reasoning field at all, which is the required shape for a non-reasoning
	// model, and leaves the request body byte-identical to a pre-reasoning one.
	ReasoningLevel reasoning.Level
	// ReasoningDialect overrides the client's default wire dialect for this
	// request. Empty falls back to the client default; when neither resolves,
	// nothing is sent rather than a guessed wire shape.
	ReasoningDialect reasoning.Dialect
	// SDKReasoningEffort is the SDK-shaped reasoning effort for one request,
	// produced by sdkadapter.LevelToReasoningEffort(ReasoningLevel). Empty
	// string means "no SDK surface" (the user picked a level the SDK cannot
	// carry on the wire, or the request is unset). Currently unused by any
	// consumer in the tree; reserved for B.2 #8's SDK-backed inner loop.
	SDKReasoningEffort sdkshape.ReasoningEffort `json:"sdk_reasoning_effort,omitempty"`
	// SessionID is the caller's session/run identifier, threaded through
	// unchanged from whatever principal issued this turn (chat session,
	// delegated subagent, workflow step). Empty means unknown - only a
	// client that opts into session-keyed routing (CompatOptions.
	// SendSessionUserKey) ever reads it, and only then does it reach the
	// wire, hashed rather than sent verbatim.
	SessionID string
}

type Response struct {
	Content          string
	ReasoningContent string
	ToolCalls        []ToolCall
	FinishReason     string
	WebSearch        []WebSearchResult
	// CacheUsage is provider-reported prompt-cache accounting for this turn.
	// Its zero value (Reported=false) means the provider reported nothing
	// recognized, not that the cache was missed.
	CacheUsage CacheUsage
	// TokenUsage is provider-reported input/output token counts for this turn.
	TokenUsage TokenUsage
}

type TokenUsage struct {
	Reported     bool
	InputTokens  int
	OutputTokens int
}

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

type ToolSpec = map[string]any

type TransientError struct{ Err error }

type WebSearchResult struct {
	Title       string `json:"title"`
	Content     string `json:"content"`
	Link        string `json:"link"`
	Media       string `json:"media"`
	Icon        string `json:"icon"`
	Refer       string `json:"refer"`
	PublishDate string `json:"publish_date"`
}