models

type BenchConfig struct {
	// Timeout is the hard cap for the whole run.
	Timeout     time.Duration
	MinInterval time.Duration
	MaxTokens   int
	SampleEvery time.Duration
}

type BenchPrompt struct {
	Name             string  `json:"name"`
	PromptTokens     int     `json:"prompt_tokens"`
	CompletionTokens int     `json:"completion_tokens"`
	TTFTMillis       int64   `json:"ttft_ms"`
	PromptTPS        float64 `json:"prompt_tokens_per_sec"`
	GenTPS           float64 `json:"gen_tokens_per_sec"`
}

type BenchRateLimitError struct{ RetryAfter time.Duration }

type BenchResult struct {
	Model            string        `json:"model"`
	RanAt            time.Time     `json:"ran_at"`
	DurationMillis   int64         `json:"duration_ms"`
	Prompts          []BenchPrompt `json:"prompts"`
	PromptTPS        float64       `json:"prompt_tokens_per_sec"`
	GenTPS           float64       `json:"gen_tokens_per_sec"`
	TTFTMillis       int64         `json:"ttft_ms"`
	PeakMemoryBytes  uint64        `json:"peak_memory_bytes"`
	MemoryLimitBytes uint64        `json:"memory_limit_bytes"`
	Truncated        bool          `json:"truncated"`
	Note             string        `json:"note"`
}

type BenchStatsFunc func(ctx context.Context, m store.Model) (used, limit uint64, ok bool)

type CPUBounds struct {
	DefaultCPUMilli  int   `json:"default_cpu_milli"`
	DefaultMemoryMiB int   `json:"default_memory_mib"`
	MaxCPUMilli      int   `json:"max_cpu_milli"`
	MaxMemoryMiB     int   `json:"max_memory_mib"`
	FreeRAMFloorMiB  int64 `json:"free_ram_floor_mib"`
}

type CPUFit struct {
	Verdict        string   `json:"verdict"`
	Reason         string   `json:"reason"`
	Suggestion     string   `json:"suggestion,omitempty"`
	SuggestedID    string   `json:"suggested_id,omitempty"`
	CPUMilli       int      `json:"cpu_milli"`
	MemoryMiB      int      `json:"memory_mib"`
	ContextTokens  int      `json:"context_tokens"`
	WeightsBytes   int64    `json:"weights_bytes"`
	WeightsSource  string   `json:"weights_source"`
	KVBytes        int64    `json:"kv_bytes"`
	OverheadBytes  int64    `json:"overhead_bytes"`
	NeedBytes      int64    `json:"need_bytes"`
	CapBytes       int64    `json:"cap_bytes"`
	DiskBytes      int64    `json:"disk_bytes"`
	DiskOK         *bool    `json:"disk_ok"`
	TokensPerSecLo float64  `json:"tokens_per_sec_low"`
	TokensPerSecHi float64  `json:"tokens_per_sec_high"`
	Estimate       bool     `json:"estimate"`
	Arithmetic     string   `json:"arithmetic"`
	Warnings       []string `json:"warnings"`
	Note           string   `json:"note"`
}

type CPUFitInput struct {
	ModelRef      string
	Quantization  string
	ContextTokens int
	// WeightsBytes is the exact file size, 0 to estimate from the name.
	WeightsBytes int64
	// ParamsB overrides the count parsed from the name when positive.
	ParamsB float64
	// EntryID is the catalog id, used to avoid suggesting the same model.
	EntryID string
	Host    HostFacts
	// CPUMilli and MemoryMiB are the requested caps, 0 for defaults.
	CPUMilli  int
	MemoryMiB int
	// DiskFreeBytes is -1 when unknown.
	DiskFreeBytes int64
}

type CPUFitReport struct {
	CPUFit
	NodeID         string        `json:"node_id"`
	HostKnown      bool          `json:"host_known"`
	HostCPUs       int           `json:"host_cpus"`
	HostMemBytes   int64         `json:"host_memory_bytes"`
	HostMemFree    int64         `json:"host_memory_available_bytes"`
	DiskFreeBytes  *int64        `json:"disk_free_bytes"`
	Entry          *CatalogEntry `json:"entry,omitempty"`
	LicenseCurated bool          `json:"license_curated"`
	LicenseNotice  string        `json:"license_notice,omitempty"`
}

type CPUFitRequest struct {
	CatalogID     string
	ModelRef      string
	Quantization  string
	ContextLength int
	WeightsBytes  int64
	NodeID        string
	CPUMilli      int
	MemoryMiB     int
}

type CPULimits struct {
	CPUMilli  int
	MemoryMiB int
	Context   int
}

type CPUPolicy struct {
	// DefaultCPUs is used when a request sets no cpu cap; 0 means min(2, half the node).
	DefaultCPUs float64
	// DefaultMemoryPercent is the default memory cap as a share of node RAM.
	DefaultMemoryPercent float64
	// MaxCPUPercent and MaxMemoryPercent bound what a request may ask for.
	MaxCPUPercent    float64
	MaxMemoryPercent float64
	// FreeRAMFloorMiB is the RAM that must stay free for other workloads
	// after the memory cap is taken.
	FreeRAMFloorMiB int64
	CPUShares       int64
	OomScoreAdj     int
	PidsLimit       int64
	// DefaultContext is the context size when the request sets none.
	DefaultContext int
	// CachePercent and CacheMaxMiB bound llama.cpp's prompt cache (-cram).
	CachePercent float64
	CacheMaxMiB  int
	// MmapHeadroomMiB is the memory left beyond the weights below which
	// weights are loaded with --no-mmap; MmapMode forces "on" or "off".
	MmapHeadroomMiB int64
	MmapMode        string
	// OverheadMiB is the engine's fixed allowance in the fit estimate.
	OverheadMiB int64
	// ComfortPercent is the share of the cap a model may use to count as comfortable.
	ComfortPercent float64
	// BandwidthPerCPUGBs and BandwidthMaxGBs drive the tokens per second estimate.
	BandwidthPerCPUGBs float64
	BandwidthMaxGBs    float64
}

type CacheBackend interface {
	ListVolumesByPrefix(ctx context.Context, prefix string) ([]docker.NamedVolume, error)
	RemoveVolume(ctx context.Context, name string) error
}

type CacheEntry struct {
	Volume         string     `json:"volume"`
	Model          string     `json:"model,omitempty"`
	Engine         string     `json:"engine,omitempty"`
	ModelRef       string     `json:"model_ref,omitempty"`
	SizeBytes      *int64     `json:"size_bytes"`
	LastUsedAt     *time.Time `json:"last_used_at"`
	LastUsedSource string     `json:"last_used_source"`
	UnusedDays     int        `json:"unused_days"`
	Unused         bool       `json:"unused"`
	InUse          bool       `json:"in_use"`
	Configured     bool       `json:"configured"`
	// DuplicateOf names the volume holding the same weights that is
	// counted in UniqueBytes instead of this one.
	DuplicateOf string `json:"duplicate_of,omitempty"`
	Prunable    bool   `json:"prunable"`
	KeepReason  string `json:"keep_reason,omitempty"`
}

type CacheNode struct {
	NodeID           string       `json:"node_id"`
	Name             string       `json:"name"`
	IsLocal          bool         `json:"is_local"`
	Supported        bool         `json:"supported"`
	Message          string       `json:"message,omitempty"`
	Entries          []CacheEntry `json:"entries"`
	TotalBytes       int64        `json:"total_bytes"`
	UniqueBytes      int64        `json:"unique_bytes"`
	ReclaimableBytes int64        `json:"reclaimable_bytes"`
	DiskFreeBytes    *int64       `json:"disk_free_bytes"`
}

type CachePruneResult struct {
	DryRun         bool         `json:"dry_run"`
	Candidates     []CacheEntry `json:"candidates"`
	Removed        []string     `json:"removed"`
	Skipped        []CacheSkip  `json:"skipped"`
	ReclaimedBytes int64        `json:"reclaimed_bytes"`
}

type CacheReport struct {
	UnusedDays int         `json:"unused_days"`
	Nodes      []CacheNode `json:"nodes"`
	Note       string      `json:"note"`
}

type CacheSkip struct {
	Volume string `json:"volume"`
	Reason string `json:"reason"`
}

type Catalog struct {
	Version    int            `json:"version"`
	VerifiedOn string         `json:"verified_on"`
	Note       string         `json:"note"`
	Models     []CatalogEntry `json:"models"`
}

type CatalogCard struct {
	CatalogEntry
	Fit CPUFit `json:"fit"`
}

type CatalogEntry struct {
	ID            string  `json:"id"`
	Label         string  `json:"label"`
	Vendor        string  `json:"vendor"`
	Repo          string  `json:"repo"`
	File          string  `json:"file"`
	ParamsB       float64 `json:"params_b"`
	Quant         string  `json:"quant"`
	DownloadBytes int64   `json:"download_bytes"`
	SHA256        string  `json:"sha256"`
	MinRAMMiB     int     `json:"min_ram_mib"`
	ContextLength int     `json:"context_length"`
	License       string  `json:"license"`
	Tier          string  `json:"tier"`
	Kind          string  `json:"kind"`
	ToolCalling   bool    `json:"tool_calling"`
	Notes         string  `json:"notes"`
}

type CatalogView struct {
	Version    int           `json:"version"`
	VerifiedOn string        `json:"verified_on"`
	Note       string        `json:"note"`
	NodeID     string        `json:"node_id"`
	HostKnown  bool          `json:"host_known"`
	HostCPUs   int           `json:"host_cpus"`
	HostMemory int64         `json:"host_memory_bytes"`
	Bounds     CPUBounds     `json:"bounds"`
	Models     []CatalogCard `json:"models"`
}

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

type CreateInput struct {
	Spec    Spec
	NodeID  string
	Domain  string
	HFToken string
	// Residency is "always" (default) or "on_demand". IdleTTL 0 uses the
	// platform default.
	Residency string
	IdleTTL   time.Duration
	// SwapGroup is empty (no group) or a name shared by other models on
	// the same node/GPU; see store.Model.SwapGroup.
	SwapGroup string
	// Compute is "" or ComputeGPU (default) or ComputeCPU. CatalogID picks a
	// curated local model and implies ComputeCPU.
	Compute   string
	CatalogID string
	// CPUMilli and MemoryMiB are the CPU model caps, 0 for the defaults.
	CPUMilli  int
	MemoryMiB int
	// WeightsFile names the GGUF file of a custom repository.
	WeightsFile string
	// LicenseAck acknowledges the licence notice of a non-curated repository.
	LicenseAck bool
}

type CreateKeyInput struct {
	Name      string
	CreatedBy string
	ExpiresAt *time.Time
	Limits    KeyLimits
}

type Created struct {
	Model  store.Model
	APIKey string
}

type CreatedKey struct {
	KeyView
	Plaintext string
}

type DiskFactsFunc func(ctx context.Context, nodeID string) (free, total int64, ok bool)

type DownloadConfig struct {
	Root     string
	BaseURL  string
	MaxBytes int64
	// HeadroomPercent is free disk required beyond the remaining bytes.
	HeadroomPercent int
	RetryAfter      time.Duration
	// BlockedRetryAfter spaces retries of failures a retry will not fix soon.
	BlockedRetryAfter time.Duration
	// HostAllowed overrides the Hugging Face host policy (tests).
	HostAllowed func(host string) bool
	Client      *http.Client
	DiskFree    func(path string) (int64, error)
	Now         func() time.Time
}

type DownloadError struct {
	Code      string
	Message   string
	Retryable bool
}

type DownloadState struct {
	Phase string
	Done  int64
	Total int64
	Err   *DownloadError
}

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

type Engine struct {
	Name         string
	DefaultImage string
	Port         int
	// CachePath is where the engine keeps downloaded weights inside the
	// container; it is backed by a persistent volume.
	CachePath string
	// RefHelp explains the model reference format for error messages.
	RefHelp string
	// contains filtered or unexported fields
}

type EngineHealth struct {
	State   string   `json:"state"`
	Summary string   `json:"summary"`
	Reasons []string `json:"reasons"`
}

type EngineMetricPoint struct {
	T time.Time `json:"t"`
	V float64   `json:"v"`
}

type EngineMetricSeries struct {
	ID        string              `json:"id"`
	Label     string              `json:"label"`
	Unit      string              `json:"unit"`
	Supported bool                `json:"supported"`
	Latest    *float64            `json:"latest"`
	Points    []EngineMetricPoint `json:"points"`
}

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

type EngineMetricsReader interface {
	Query(ctx context.Context, resourceID, metric string, from, to time.Time) ([]telemetry.Sample, error)
}

type EngineMetricsReport struct {
	Model      string               `json:"model"`
	Engine     string               `json:"engine"`
	From       time.Time            `json:"from"`
	To         time.Time            `json:"to"`
	Collecting bool                 `json:"collecting"`
	Note       string               `json:"note"`
	Health     EngineHealth         `json:"health"`
	Series     []EngineMetricSeries `json:"series"`
}

type EngineMetricsStore interface {
	ListModels(ctx context.Context) ([]store.Model, error)
}

type FitConfig struct {
	// OverheadPercent is added to weight bytes for KV cache and buffers.
	OverheadPercent float64
	// FitPercent is the share of free VRAM a model may use to count as
	// "fits"; above it (up to 100%) it is "tight".
	FitPercent float64
	// DiskHeadroomPercent is extra free disk required beyond the download.
	DiskHeadroomPercent float64
}

type FitDetail struct {
	Verdict        string   `json:"verdict"`
	WeightsSource  string   `json:"weights_source"`
	WeightsBytes   int64    `json:"weights_bytes"`
	KVBytes        int64    `json:"kv_bytes"`
	OverheadBytes  int64    `json:"overhead_bytes"`
	NeedBytes      int64    `json:"need_bytes"`
	FreeBytes      int64    `json:"free_bytes"`
	ContextTokens  int      `json:"context_tokens"`
	ContextAssumed bool     `json:"context_assumed"`
	Arithmetic     string   `json:"arithmetic"`
	Reason         string   `json:"reason,omitempty"`
	Suggestions    []string `json:"suggestions"`
}

type FitInput struct {
	Engine        string
	ModelRef      string
	Quantization  string
	ContextLength int
	// WeightsBytes is the exact download size when known; 0 means estimate.
	WeightsBytes int64
	// GPUs is how many GPUs the model spreads over.
	GPUs int
	// FreeBytes is the total free VRAM across those GPUs; MinFreeBytes and
	// MinTotalBytes describe the tightest single GPU.
	FreeBytes     int64
	MinFreeBytes  int64
	MinTotalBytes int64
}

type FitParams struct {
	// GPUOverheadMiB is reserved per GPU for the CUDA context and buffers.
	GPUOverheadMiB int64
	// VLLMExtraMiB is added per GPU for vLLM's CUDA graphs and torch context.
	VLLMExtraMiB int64
	// DefaultContext is assumed when a model sets no context length.
	DefaultContext int
	// VLLMUtilization is the share of each GPU vLLM pre-allocates.
	VLLMUtilization float64
	// KVKiBPerToken overrides the parameter-count heuristic when positive.
	KVKiBPerToken float64
}

type FitReport struct {
	Model string    `json:"model,omitempty"`
	Nodes []NodeFit `json:"nodes"`
	Note  string    `json:"note"`
}

type FitRequest struct {
	Engine        string
	ModelRef      string
	Quantization  string
	ContextLength int
	GPUCount      int
	GPUDeviceIDs  []string
	// WeightsBytes is the exact size from a preflight, 0 to estimate.
	WeightsBytes int64
	// NodeID limits the check to one node; nil checks every GPU node.
	NodeID *string
}

type GPUNode struct {
	NodeID     string
	Name       string
	IsLocal    bool
	Info       gpu.Info
	UpdatedAt  time.Time
	ModelCount int
	// PlacementID is the node ID as services and models record it: "" for
	// the control plane's own host.
	PlacementID string
	Schedulable bool
	Online      bool
	Claims      []gpu.Claim
}

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

type GatewayLimits struct {
	MaxBodyBytes  int64
	MaxN          int
	MaxTokens     int
	MaxInflight   int
	RetryAfter    time.Duration
	DialTimeout   time.Duration
	HeaderTimeout time.Duration
	IdleTimeout   time.Duration
	// WakeWait bounds how long a request to a sleeping on-demand model is
	// held while its engine loads; zero fails fast with Retry-After.
	WakeWait       time.Duration
	WakeRetryAfter time.Duration
	// TouchInterval throttles how often gateway activity is written.
	TouchInterval time.Duration
}

type GatewayLimitsSummary struct {
	MaxBodyBytes           int64 `json:"max_body_bytes"`
	MaxN                   int   `json:"max_n"`
	MaxTokens              int   `json:"max_tokens"`
	MaxInflight            int   `json:"max_inflight_requests"`
	ResponseHeaderTimeoutS int   `json:"response_header_timeout_seconds"`
	StreamIdleTimeoutS     int   `json:"stream_idle_timeout_seconds"`
}

type GatewayStore interface {
	ListModels(ctx context.Context) ([]store.Model, error)
	ListActiveModelKeys(ctx context.Context) ([]store.ModelKey, error)
}

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

type HFConfig struct {
	BaseURL          string
	Timeout          time.Duration
	CacheTTL         time.Duration
	MaxResponseBytes int64
	CacheEntries     int
}

type HFError struct {
	Status     string
	Message    string
	RetryAfter time.Duration
}

type HFFile struct {
	Name  string `json:"name"`
	Bytes int64  `json:"bytes"`
}

type HFRepo struct {
	ID      string
	Gated   string
	Private bool
	License string
	Files   []HFFile
	// Access is "granted", "denied" or "unknown" for a gated repo, and
	// "not_required" otherwise.
	Access string
}

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

type HostFacts struct {
	CPUs          int
	MemTotalBytes int64
	// MemAvailBytes is currently available memory, 0 when unknown.
	MemAvailBytes int64
}

type HostFactsFunc func(ctx context.Context, nodeID string) (HostFacts, bool)

type HostLister struct {
	Store GatewayStore
	Hosts *HostResolver
}

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

type KeyLimits struct {
	RPM         int
	TPM         int
	TPD         int
	MaxParallel int
	AllowPaths  []string
	AllowModels []string
}

type KeyStatus string

type KeyUsage struct {
	KeyID     string `json:"key_id"`
	Name      string `json:"name"`
	KeyPrefix string `json:"key_prefix"`
	Status    string `json:"status"`
	InFlight  int    `json:"in_flight"`
	UsageTotals
}

type KeyView struct {
	store.ModelKey
	Status   KeyStatus
	InFlight int
}

type MeterConfig struct {
	FlushInterval time.Duration
	BatchSize     int
	MaxBuffered   int
	Retention     time.Duration
	ScanBytes     int
}

type NodeFit struct {
	NodeID   string `json:"node_id"`
	Name     string `json:"name"`
	IsLocal  bool   `json:"is_local"`
	Eligible bool   `json:"eligible"`
	// Current marks the node a deployed model already runs on.
	Current    bool  `json:"current"`
	GPUs       int   `json:"gpus"`
	TotalBytes int64 `json:"total_bytes"`
	// ReservedBytes is VRAM estimated for other models placed here that are
	// not loaded yet, already subtracted from free.
	ReservedBytes int64 `json:"reserved_bytes"`
	FitDetail
}

type NodeInfo struct {
	GPU gpu.Info
	// BindIP is the address the engine's port is published on.
	BindIP string
	// DialHost is the address the control plane reaches BindIP at. Empty
	// means the node is remote and not on the mesh.
	DialHost string
	// Local is true for the control plane's own host, the only node whose
	// filesystem the control plane can download weights onto.
	Local bool
}

type Nodes interface {
	NodeInfo(ctx context.Context, nodeID string) (NodeInfo, error)
}

type Option func(*Controller)

type Phase string

type PreflightDisk struct {
	Status        string `json:"status"`
	RequiredBytes int64  `json:"required_bytes"`
	FreeBytes     *int64 `json:"free_bytes"`
	Message       string `json:"message"`
}

type PreflightFile struct {
	Name  string `json:"name"`
	Bytes int64  `json:"bytes"`
}

type PreflightInput struct {
	// Repo is "owner/name", optionally ":quant", or a huggingface.co URL.
	Repo   string
	Engine string
	File   string
	Quant  string
	NodeID string
	// GPUCount is how many GPUs the model will use; 0 or less means all.
	GPUCount int
	// Token is used for this request only and never stored or logged.
	Token string
}

type PreflightNode struct {
	NodeID         string `json:"node_id"`
	GPUPresent     bool   `json:"gpu_present"`
	VRAMTotalBytes *int64 `json:"vram_total_bytes"`
	VRAMFreeBytes  *int64 `json:"vram_free_bytes"`
	DiskFreeBytes  *int64 `json:"disk_free_bytes"`
	DiskTotalBytes *int64 `json:"disk_total_bytes"`
}

type PreflightResult struct {
	Repo               string              `json:"repo"`
	Status             string              `json:"status"`
	Exists             bool                `json:"exists"`
	Message            string              `json:"message"`
	NextStep           string              `json:"next_step,omitempty"`
	RetryAfterSeconds  int                 `json:"retry_after_seconds,omitempty"`
	Gated              string              `json:"gated,omitempty"`
	Access             string              `json:"access,omitempty"`
	Private            bool                `json:"private"`
	License            string              `json:"license,omitempty"`
	TotalBytes         int64               `json:"total_bytes"`
	FileCount          int                 `json:"file_count"`
	Files              []PreflightFile     `json:"files"`
	FilesTruncated     bool                `json:"files_truncated"`
	HasGGUF            bool                `json:"has_gguf"`
	HasSafetensors     bool                `json:"has_safetensors"`
	CompatibleEngines  []string            `json:"compatible_engines"`
	EngineHint         string              `json:"engine_hint"`
	Quants             []Quant             `json:"quants"`
	RecommendedQuant   string              `json:"recommended_quant,omitempty"`
	RecommendationNote string              `json:"recommendation_note,omitempty"`
	Selected           *PreflightSelection `json:"selected,omitempty"`
	Node               PreflightNode       `json:"node"`
	Disk               PreflightDisk       `json:"disk"`
	Warnings           []string            `json:"warnings"`
	EstimateNote       string              `json:"estimate_note"`
	Cached             bool                `json:"cached"`
}

type PreflightSelection struct {
	Label string `json:"label"`
	Bytes int64  `json:"bytes"`
	Fit   string `json:"fit"`
}

type Prober interface {
	Probe(ctx context.Context, engine, dial, modelRef string) Status
}

type Quant struct {
	Name        string   `json:"name"`
	Bytes       int64    `json:"bytes"`
	Files       []string `json:"files"`
	Fit         string   `json:"fit"`
	Recommended bool     `json:"recommended"`
}

type SampleWriter interface {
	WriteSamples(ctx context.Context, samples []telemetry.Sample) error
}

type SecretWriter interface {
	SetValue(ctx context.Context, serviceName, envKey, plaintext string) error
	DeleteAll(ctx context.Context, serviceName string) error
}

type Secrets interface {
	Resolve(ctx context.Context, serviceName, envKey string) (string, error)
	DeleteAll(ctx context.Context, serviceName string) error
}

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

type ServiceStore interface {
	SaveModel(ctx context.Context, m store.Model) error
	GetModel(ctx context.Context, name string) (*store.Model, error)
	ListModels(ctx context.Context) ([]store.Model, error)
	DeleteModel(ctx context.Context, name string) error
	MarkModelDeleting(ctx context.Context, name string) error
	RotateModelAPIKey(ctx context.Context, name, hash, prefix string) error
	ListModelKeys(ctx context.Context, model string) ([]store.ModelKey, error)
	GetModelKey(ctx context.Context, model, id string) (*store.ModelKey, error)
	CreateModelKey(ctx context.Context, k store.ModelKey) error
	RevokeModelKey(ctx context.Context, model, id string, now time.Time) error
	RotateModelKey(ctx context.Context, model, oldID string, next store.ModelKey, graceUntil *time.Time, now time.Time) error
	ListModelUsage(ctx context.Context, model string, from, to time.Time) ([]store.ModelUsage, error)
	RestartModel(ctx context.Context, name string) error
	SetModelBenchmark(ctx context.Context, name, resultJSON string) error
	SetModelHFTokenSet(ctx context.Context, name string, set bool) error
	SetModelResidency(ctx context.Context, name, residency string, idleTTLSeconds int, now time.Time) error
	TouchModel(ctx context.Context, name string, at time.Time) error
	SleepModel(ctx context.Context, name string) error
	SetModelSwapGroup(ctx context.Context, name, group string) error
	ListModelsInSwapGroup(ctx context.Context, group string) ([]store.Model, error)
	GetConditions(ctx context.Context, controllerName string) ([]reconcile.Condition, error)
	GetConditionsForControllers(ctx context.Context, controllerNames []string) (map[string][]reconcile.Condition, error)
	GetNode(ctx context.Context, id string) (*store.Node, error)
	GetNodeGPU(ctx context.Context, nodeID string) (store.NodeGPU, bool, error)
	ListNodes(ctx context.Context) ([]store.Node, error)
	ListNodeGPUs(ctx context.Context) (map[string]store.NodeGPU, error)
	ListDesiredServices(ctx context.Context) ([]store.DesiredService, error)
}

type Spec struct {
	Name          string
	Engine        string
	ModelRef      string
	GPUCount      int
	GPUDeviceIDs  []string
	ContextLength int
	Quantization  string
	// Compute is "" or ComputeGPU (default) or ComputeCPU.
	Compute string
}

type Status struct {
	Phase  Phase
	Detail string
}

type Store interface {
	GetModel(ctx context.Context, name string) (*store.Model, error)
	SetModelEndpoint(ctx context.Context, name, dial string) error
	SetModelResidencyState(ctx context.Context, name, state string) error
	DeleteModel(ctx context.Context, name string) error
	// ListModelsInSwapGroup backs swap group eviction (residency.go's
	// waitForGPUWithSwap): finding a resident sibling to stop before
	// waking a model that would otherwise not fit.
	ListModelsInSwapGroup(ctx context.Context, group string) ([]store.Model, error)
}

type Unplaced struct {
	Kind   string
	Name   string
	NodeID string
	Reason string
}

type UsagePoint struct {
	Hour time.Time `json:"hour"`
	UsageTotals
}

type UsageReport struct {
	Model    string       `json:"model"`
	From     time.Time    `json:"from"`
	To       time.Time    `json:"to"`
	Totals   UsageTotals  `json:"totals"`
	Series   []UsagePoint `json:"series"`
	Keys     []KeyUsage   `json:"keys"`
	InFlight int          `json:"in_flight"`
	Note     string       `json:"note"`
}

type UsageStore interface {
	AddModelUsage(ctx context.Context, rows []store.ModelUsage) error
	TouchModelKeys(ctx context.Context, used map[string]time.Time) error
	PruneModelUsage(ctx context.Context, before time.Time) (int64, error)
}

type UsageTotals struct {
	Requests      int64 `json:"requests"`
	Status2xx     int64 `json:"status_2xx"`
	Status4xx     int64 `json:"status_4xx"`
	Status5xx     int64 `json:"status_5xx"`
	RateLimited   int64 `json:"rate_limited"`
	UsageRequests int64 `json:"usage_requests"`
	InputTokens   int64 `json:"input_tokens"`
	OutputTokens  int64 `json:"output_tokens"`
	BytesOut      int64 `json:"bytes_out"`
	AvgDurationMs int64 `json:"avg_duration_ms"`
	AvgTTFTMs     int64 `json:"avg_ttft_ms"`
	// contains filtered or unexported fields
}

type View struct {
	Model   store.Model
	Ready   bool
	Reason  string
	Message string
	BaseURL string
	// SharesGPUWith is every other model in the same non-empty
	// SwapGroup on the same node, excluding this one.
	SharesGPUWith []string
}

type WakeStore interface {
	GetModel(ctx context.Context, name string) (*store.Model, error)
	TouchModel(ctx context.Context, name string, at time.Time) error
}

type Weights interface {
	Ensure(spec WeightsSpec) DownloadState
	Dir(name string) string
	Forget(name string)
}

type WeightsSpec struct {
	Name string
	Repo string
	File string
	// SHA256 is the expected digest; empty falls back to the digest the
	// Hub reports on the response (X-Linked-Etag), and to none for a file
	// the Hub gives no digest for.
	SHA256 string
	Token  string
	// Key changes when the download should be retried from scratch, for
	// example after a new token or a restart.
	Key string
}