models

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 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
}

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 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 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
}

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
	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
}

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
}