model

type BreakerConfig struct {
	// WindowSize is the number of recent results to keep per endpoint.
	// Older results slide out as new ones arrive. Must be >= 1.
	// Default: 20.
	WindowSize int

	// MinRequests is the minimum number of observations before the
	// error rate is consulted. Below this, the endpoint stays Closed
	// regardless of failure ratio. Prevents one-or-two-error flukes
	// on cold endpoints from opening the breaker. Must be <= WindowSize.
	// Default: 5.
	MinRequests int

	// ErrorRateThreshold is the failure ratio above which the breaker
	// opens (assuming MinRequests has been met). 0.5 means "open if
	// more than half the recent window failed." Must be in (0, 1].
	// Default: 0.5.
	ErrorRateThreshold float64

	// Cooldown is the wait between Open and HalfOpen — how long the
	// endpoint stays out of rotation before we send a probe. Must be > 0.
	// Default: 30s.
	Cooldown time.Duration

	// Now is the time source. Tests inject a clock; production leaves
	// this nil and time.Now is used.
	Now func() time.Time
}

type CapabilityConfig struct {
	// Description explains what this capability is for.
	Description string `json:"description,omitempty"`
	// Preferred lists endpoint names in order of preference.
	Preferred []string `json:"preferred"`
	// Fallback lists backup endpoint names if all preferred are unavailable.
	Fallback []string `json:"fallback,omitempty"`
	// RequiresTools filters the chain to only tool-capable endpoints.
	RequiresTools bool `json:"requires_tools,omitempty"`
	// Timeout caps a single LLM request routed via this capability.
	// Go duration string (e.g. "45s", "5m"). Empty means no per-capability
	// cap; the component-level timeout applies. Endpoint and task timeouts
	// take precedence over this value. See agentic-model Timeout Resolution
	// for the full precedence chain.
	Timeout string `json:"timeout,omitempty"`
}

type DefaultsConfig struct {
	// Model is the default endpoint name when no capability matches.
	Model string `json:"model"`
	// Capability is the default capability when none specified.
	Capability string `json:"capability,omitempty"`
}

type EndpointConfig struct {
	// Provider identifies the API type: "anthropic", "ollama", "openai", "openrouter".
	Provider string `json:"provider"`
	// URL is the API endpoint. Required for ollama/openai/openrouter, optional for anthropic.
	URL string `json:"url,omitempty"`
	// Model is the model identifier sent to the provider.
	Model string `json:"model"`
	// MaxTokens is the context window size in tokens.
	//
	// For provider="ollama", this value is NOT forwarded to the server —
	// Ollama's /v1/chat/completions layer rejects per-request num_ctx by
	// design. Pre-build a Modelfile with PARAMETER num_ctx <N> and point
	// endpoint.model at the derived name. See
	// docs/operations/04-ollama-setup.md. On first request to an Ollama
	// endpoint, agentic-model probes /api/show and WARNs once if the
	// model's num_ctx is below this value.
	//
	// For all other providers this value is used only for summarization
	// routing (picking the largest-context endpoint) and context-budget
	// math in agentic-loop — the provider determines the actual window.
	MaxTokens int `json:"max_tokens"`
	// SupportsTools indicates whether this endpoint supports function/tool calling.
	SupportsTools bool `json:"supports_tools,omitempty"`
	// ToolFormat specifies the tool calling format: "anthropic" or "openai".
	// Empty means auto-detect from provider.
	ToolFormat string `json:"tool_format,omitempty"`
	// APIKeyEnv is the environment variable containing the API key.
	// Required for anthropic/openai/openrouter, ignored for ollama.
	APIKeyEnv string `json:"api_key_env,omitempty"`
	// Options holds provider-specific template parameters passed to the API
	// as chat_template_kwargs. For vLLM/SGLang with thinking models, set
	// "enable_thinking" and "thinking_budget" here.
	//
	// Note: Ollama's OpenAI-compatible endpoint ignores chat_template_kwargs.
	// Ollama thinking models (Qwen3, DeepSeek-R1) always return reasoning_content
	// but the thinking toggle and budget are only controllable via Ollama's
	// native /api/chat endpoint, not the OpenAI-compatible /v1/ endpoint.
	//
	// Do not use for inference parameters (temperature, top_k, etc.) which
	// have dedicated fields in AgentRequest.
	Options map[string]any `json:"options,omitempty"`
	// Stream enables SSE streaming for this endpoint. The client uses
	// CreateChatCompletionStream internally, reducing time-to-first-token.
	// The inter-component protocol remains complete AgentResponse messages.
	Stream bool `json:"stream,omitempty"`
	// ReasoningEffort controls how much effort reasoning models spend thinking.
	// Accepted values: "none" (Gemini only), "low", "medium", "high".
	// Empty means the provider default is used. Forwarded as reasoning_effort
	// on the OpenAI-compatible chat completions request.
	ReasoningEffort string `json:"reasoning_effort,omitempty"`
	// InputPricePer1MTokens is the cost per 1M input tokens in USD.
	// Consumers join this with token usage data to calculate costs.
	InputPricePer1MTokens float64 `json:"input_price_per_1m_tokens,omitempty"`
	// OutputPricePer1MTokens is the cost per 1M output tokens in USD.
	// Consumers join this with token usage data to calculate costs.
	OutputPricePer1MTokens float64 `json:"output_price_per_1m_tokens,omitempty"`
	// RequestsPerMinute limits the rate of requests to this endpoint.
	// 0 means no rate limiting. Applied per-endpoint across all consumers.
	RequestsPerMinute int `json:"requests_per_minute,omitempty"`
	// MaxConcurrent limits concurrent in-flight requests to this endpoint.
	// 0 means no concurrency limit.
	MaxConcurrent int `json:"max_concurrent,omitempty"`
	// RequestTimeout caps a single LLM request to this endpoint.
	// Go duration string (e.g. "45s", "5m"). Empty means no per-endpoint cap;
	// the capability or component-level timeout applies. See agentic-model
	// Timeout Resolution for the full precedence chain.
	RequestTimeout string `json:"request_timeout,omitempty"`
}

type EndpointStatus int

type ErrorKind string

type HealthAwareRegistry interface {
	RegistryReader
	HealthPolicy
}

type HealthPolicy interface {
	// IsHealthy returns true iff the endpoint is eligible to receive
	// new requests. Equivalent to EndpointStatus(name) != StatusOpen
	// (the half-open state allows one probe through).
	IsHealthy(endpoint string) bool

	// EndpointStatus returns the current circuit-breaker state for
	// the named endpoint. Unknown endpoints (no observations yet)
	// must return StatusClosed — new endpoints are healthy by default.
	EndpointStatus(endpoint string) EndpointStatus

	// EndpointStats returns a snapshot of the endpoint's recent
	// observation window. Unknown endpoints return a zero HealthStats
	// with Status=StatusClosed.
	EndpointStats(endpoint string) HealthStats

	// RecordResult tells the policy that endpoint just produced
	// the given result. Drives state transitions on the next call.
	// Safe to call concurrently from multiple request goroutines
	// targeting the same endpoint.
	RecordResult(endpoint string, result Result)
}

type HealthStats struct {
	// Status is the current circuit-breaker state.
	Status EndpointStatus
	// Successes is the count of successful results in the window.
	Successes int
	// Failures is the count of failed results in the window.
	Failures int
	// ErrorRate is Failures / (Successes + Failures); 0 if no
	// observations yet.
	ErrorRate float64
	// LastFailure is the time of the most recent failure (zero if no
	// failure has been observed in the window).
	LastFailure time.Time
	// LastTransition is the time of the most recent state change.
	// Useful for "how long has this endpoint been open?" dashboards.
	LastTransition time.Time
}

type Registry struct {
	Capabilities map[string]*CapabilityConfig `json:"capabilities,omitempty"`
	Endpoints    map[string]*EndpointConfig   `json:"endpoints"`
	Defaults     DefaultsConfig               `json:"defaults"`
}

type RegistryReader interface {
	// Resolve returns the preferred endpoint name for a capability.
	// Returns the first endpoint in the preferred list.
	// If RequiresTools is set, filters to tool-capable endpoints.
	Resolve(capability string) string

	// GetFallbackChain returns all endpoint names for a capability in preference order.
	// Includes both preferred and fallback endpoints.
	GetFallbackChain(capability string) []string

	// GetEndpoint returns the full endpoint configuration for an endpoint name.
	// Returns nil if the endpoint is not configured.
	GetEndpoint(name string) *EndpointConfig

	// GetCapability returns the full capability configuration for a capability
	// name. Returns nil if the name is not a configured capability (e.g. when
	// the caller passed an endpoint name instead).
	GetCapability(name string) *CapabilityConfig

	// GetMaxTokens returns the context window size for an endpoint name.
	// Returns 0 if the endpoint is not configured.
	GetMaxTokens(name string) int

	// GetDefault returns the default endpoint name.
	GetDefault() string

	// ListCapabilities returns all configured capability names sorted alphabetically.
	ListCapabilities() []string

	// ListEndpoints returns all configured endpoint names sorted alphabetically.
	ListEndpoints() []string

	// ResolveSummarization returns the endpoint name to use for context summarization.
	// Resolution order:
	//  1. Explicit "summarization" capability if configured
	//  2. Endpoint with the largest MaxTokens (best suited for long context summarization)
	//  3. The default endpoint as final fallback
	ResolveSummarization() string
}

type ResolvedEndpoint struct {
	URL    string
	Model  string
	APIKey string
}

type Result struct {
	// Success is true iff the request returned a usable response after
	// any internal retry. Transient retries that ultimately succeeded
	// should be reported as Success=true with ErrorKindNone.
	Success bool
	// Kind classifies the failure for metrics and breaker tuning;
	// ErrorKindNone on success.
	Kind ErrorKind
	// Latency is wall time spent on the request from caller dispatch
	// to result. Includes retry time. Zero is acceptable when the
	// caller doesn't measure (e.g., synthetic results in tests).
	Latency time.Duration
}

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

type Watcher interface {
	WatchModelRegistry() <-chan *Registry
}