openai

type Config struct {
	BaseURL      string // e.g., "http://localhost:1234/v1" for LM Studio
	APIKey       string // optional for local providers
	Model        string // e.g., "qwen3.5-7b", "gpt-4o". Empty = auto-discover.
	ProviderName string // logical provider identity; default "openai"
	// ProviderSystem is the telemetry/cost system identity. When empty, it
	// defaults to "openai". Concrete provider wrappers set their own type.
	ProviderSystem string
	ModelPattern   string // case-insensitive regex to prefer among auto-discovered models
	// KnownModels maps concrete model IDs to catalog target IDs for the
	// agent.openai surface. Models present in this map are ranked higher during
	// auto-selection. Populated by the config layer from the model catalog;
	// nil disables catalog-aware ranking.
	KnownModels map[string]string
	Headers     map[string]string // extra HTTP headers (OpenRouter, Azure, etc.)
	Reasoning   reasoningpolicy.Reasoning
	// Capabilities supplies provider-owned protocol capability claims. When nil,
	// direct openai.Provider callers use OpenAI protocol defaults.
	Capabilities *ProtocolCapabilities
	// UsageCostAttribution extracts provider-owned gateway cost metadata from
	// the raw usage object, when that provider reports one.
	UsageCostAttribution func(rawUsage string) (*agent.CostAttribution, bool)
	// ModelReasoningWire maps a concrete model ID to the catalog
	// reasoning_wire value for that model. Recognized values are "provider"
	// (default), "model_id" (model name encodes reasoning level — strip the
	// reasoning field at serialization), and "none" (model has no reasoning
	// surface — reject explicit non-off requests pre-flight). Models not
	// listed default to "provider", preserving existing behavior.
	ModelReasoningWire map[string]string
	// QuotaHeaderParser, when set, overrides the default OpenAI rate-limit
	// header parser. OpenRouter uses this to install
	// quotaheaders.ParseOpenRouter even though it goes through this
	// OpenAI-compatible provider implementation.
	QuotaHeaderParser func(http.Header, time.Time) quotaheaders.Signal
	// QuotaSignalObserver receives parsed rate-limit signals on every
	// response. The service layer wires this to the provider quota state
	// machine. Both QuotaHeaderParser and QuotaSignalObserver must be set
	// for header-driven exhaustion tracking to activate.
	QuotaSignalObserver func(quotaheaders.Signal)
}

type HTTPStatusError struct {
	Endpoint   string
	Operation  string
	StatusCode int
	Body       string
}

type ProtocolCapabilities struct {
	Tools            bool
	Stream           bool
	StructuredOutput bool
	// Thinking reports whether the provider accepts non-standard body fields
	// (openai-go WithJSONSet) used to control model-side reasoning.
	Thinking       bool
	ThinkingFormat ThinkingWireFormat
	// StrictThinkingModelMatch, when true, makes the openai layer return an
	// error if the request carries an explicit reasoning policy while the
	// model does not match the provider's wire format family (e.g. a Qwen
	// wire format with a non-Qwen model). Set true for providers that only
	// serve a single model family (OMLX → Qwen MLX). Providers that host
	// mixed model families (LM Studio can load Qwen, Gemma, Llama, etc.)
	// should leave this false so reasoning controls silently no-op on
	// non-matching models instead of failing the request.
	StrictThinkingModelMatch bool
	// ImplicitGenerationConfig declares that the inference server applies
	// the model's HuggingFace `generation_config.json` automatically when
	// the request omits sampler fields. vLLM does this by default; most
	// other local servers (omlx, lmstudio, lucebox) ship custom presets and
	// either ignore upstream defaults or replace them at repackage time
	// (MLX / GGUF strip generation_config.json), which is why ADR-007's
	// catalog sampling_profiles exist. Routing and the catalog-stale
	// nudge use this flag to distinguish "server has a sane default" from
	// "server will decode greedy" when no catalog profile is supplied.
	ImplicitGenerationConfig bool
}

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

type ReachabilityError struct {
	// Endpoint is the base URL of the provider that failed.
	Endpoint string
	// Operation identifies what was being attempted when the failure
	// occurred. Typical values: "probe_models", "chat_completions".
	Operation string
	// StatusCode is the HTTP status code if the failure was HTTP-level;
	// 0 for non-HTTP failures (dial error, timeout, TLS handshake, etc.).
	StatusCode int
	// Cause is the underlying error.
	Cause error
}

type ScoredModel struct {
	// ID is the model identifier returned by the server's /v1/models endpoint.
	ID string
	// CatalogRef is the catalog target ID if this model is recognized in the
	// model catalog for the provider's surface. Empty for unrecognized models.
	CatalogRef string
	// PatternMatch is true when this model matched the configured model_pattern.
	PatternMatch bool
	// Score summarises the selection preference: 3 = catalog-recognized,
	// 2 = pattern-matched, 1 = uncategorized.
	Score int
}

type ThinkingWireFormat string