package proxy

// Backend represents one upstream free-model provider (opencode zen, kilo, mimo, ...).
//
// Each backend knows its own model catalogue, how to resolve a requested model
// name to the upstream ID, and the URL + headers required to forward a chat
// completion request to it. The Proxy holds an ordered list of backends and
// routes each request to the first one that recognises the model.
type Backend interface {
	// Name is a short stable identifier ("opencode", "kilo").
	Name() string

	// Models returns the free models this backend exposes, for /v1/models listing.
	Models() []ModelInfo

	// Resolve maps a client-requested model name to the upstream model ID.
	// Returns ok=false when this backend does not recognise the model, so the
	// router can try the next backend (or fall back to pass-through).
	Resolve(model string) (resolved string, ok bool)

	// ChatURL is the full upstream chat completions URL.
	ChatURL() string

	// Headers returns the headers required to authenticate/identify the
	// request to the upstream (auth, client-id, request/session tracking, etc.).
	Headers(requestID, sessionID string) map[string]string
}