modelregistry

type FamilyGroup struct {
	Family  string
	Entries []ModelDescriptor
}

type ModelDescriptor struct {
	ID        string `json:"id,omitempty" example:"m1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6"`
	Name      string `json:"name" example:"qwen3-8b"`
	SourceURL string `json:"sourceUrl" example:"https://huggingface.co/Qwen/..."`
	SizeBytes int64  `json:"sizeBytes" example:"934000000"`
	Curated   bool   `json:"curated" example:"true"`
	// Backend is the local backend this model targets: "" or "llama" for GGUF,
	// "openvino" for an OpenVINO IR model. It selects the models/<backend>/
	// directory and the pull strategy (single GGUF file vs multi-file IR repo).
	Backend string `json:"backend,omitempty" example:"openvino"`
	// Repo is the Hugging Face repo id for multi-file pulls (OpenVINO IR). For
	// GGUF models SourceURL points at the single file and Repo is empty.
	Repo string `json:"repo,omitempty" example:"OpenVINO/Qwen3-8B-int4-ov"`
	// ToolProtocol is the backend-native tool-call parser protocol (for example
	// "llama:common_chat_tool_parser" or "openvino:...").
	// Set for curated models certified for tool calls; `model pull` writes it into
	// the model's profile so the local provider enables tool calls out of the box.
	ToolProtocol string `json:"toolProtocol,omitempty" example:"llama:common_chat_tool_parser"`
	// ReasoningProtocol is the local backend's parser for model-emitted reasoning
	// text. `model pull` writes it into the
	// model's profile so the provider can separate visible output from thinking.
	ReasoningProtocol string `json:"reasoningProtocol,omitempty" example:"llama:common_chat_reasoning_parser"`
	// ReasoningFormat is the backend-native reasoning format passed to the parser
	// and chat-template renderer, for example llama.cpp common-chat "deepseek".
	ReasoningFormat string `json:"reasoningFormat,omitempty" example:"deepseek"`
	// Family groups related size/quant variants of the same model line for
	// display (e.g. "qwen3", "gemma4", "phi-4"). It is a presentation grouping
	// key, not a capability signal.
	Family string `json:"family,omitempty" example:"qwen3"`
	// DisplayLabel is the human-readable name shown in listings, e.g.
	// "Qwen 3 8B". Falls back to Name when empty.
	DisplayLabel string `json:"displayLabel,omitempty" example:"Qwen 3 8B"`
	// UseCase is the primary workflow this curated entry is meant to serve,
	// e.g. "coding", "chat", "reasoning", or "smoke".
	UseCase string `json:"useCase,omitempty" example:"coding"`
	// RecommendedVRAMGB is the coarse VRAM tier this curated entry is intended
	// for before live modeld capacity data is available. It is advisory only:
	// modeld still resolves the real hot-KV/effective-context fit from current
	// device free memory, resident policy, KV profile, and runtime overhead.
	RecommendedVRAMGB int `json:"recommendedVramGb,omitempty" example:"8"`
	// Notes is a short free-text annotation shown alongside the model in
	// listings, e.g. "native tool format", "MoE", "fastest smoke test".
	Notes string `json:"notes,omitempty" example:"native tool format"`
}

type Registry interface {
	// Resolve returns the descriptor for name from curated or user-added entries.
	Resolve(ctx context.Context, name string) (*ModelDescriptor, error)
	// List returns all known descriptors (curated + user-added). User entries override curated SourceURL.
	List(ctx context.Context) ([]ModelDescriptor, error)
	// OptimalFor returns the best registry name for an arbitrary model name string.
	// Exact match → family mapping → fallback.
	OptimalFor(ctx context.Context, modelName string) (string, error)
}