fix(distributed): backend discovery hid GPU-only backends behind the controller's capability

[localai-bot]

Capability-filtered backend discovery evaluated compatibility against the host serving the request. In a distributed deployment that host is the controller — typically a GPU-less pod — while the GPUs live on worker nodes.

Any meta backend whose capabilities: map lacks a default (or cpu) key was dropped entirely. On a live cluster, GET /backends/available returned 275 entries with zero longcat/l4t entries: longcat-video, vllm-omni, ltx-video, parakeet, edgetam and qwentts were invisible in the UI, even though installing them by name on a GPU worker works fine — DistributedBackendManager.InstallBackend ships only the backend name, which the worker resolves against its own hardware.

Confirmed against backend/index.yaml: the present/absent split falls exactly along whether a meta declares a default key.

• PRESENT: llama-cpp, whisper, vibevoice, moss-tts-cpp, rfdetr, depth-anything, mlx, vllm (all have default)
• ABSENT: longcat-video (nvidia keys only), vllm-omni (nvidia + amd only)

Root cause

ListAvailableBackendsEndpoint (core/http/endpoints/localai/backend.go:331) calls gallery.AvailableBackends(...) → availableBackendsWithFilter(..., filterByCapability=true) (core/gallery/gallery.go:397), which filters on backend.IsCompatibleWith(systemState) using the controller's system state. For a meta backend that resolves to CapabilitiesMap[systemState.Capability(...)]; on a GPU-less controller getSystemCapabilities() returns default and Capability() falls back default → cpu, so a meta with neither key is dropped.

Fix

Workers report their own meta-backend capability at registration; the controller persists it on the node row (capability column, AutoMigrate). The controller cannot derive it — OS-dependent capabilities (metal, darwin-x86, nvidia-l4t) and CUDA-runtime refinements are only observable on the worker, and a node's gpu_vendor is empty on Apple Silicon. Nodes registered before this field fall back to a coarse capability from GPU vendor + VRAM.

Discovery then unions capabilities over healthy backend nodes (status = healthy AND node_type = backend, matching the scheduler's own predicate). Each remote capability is evaluated through a capability-pinned SystemState, so a forced capability on the controller image (LOCALAI_FORCE_META_BACKEND_CAPABILITY / /run/localai/capability) cannot override a worker's verdict.

An empty node list reproduces the previous listing exactly — single-node behavior is untouched. A registry error degrades to the local-only listing rather than blanking the catalog or 500-ing.

Four surfaces fixed

• GET /backends/available
• GET /api/fine-tuning/backends (finetune.go:279)
• GET /api/quantization/backends (quantization.go:198)
• /api/operations backend-vs-model classification (ui_api.go:216) — now unfiltered: a GPU-only backend installing on a worker is still a backend op on the controller, and was being misclassified as a model op

The fine-tune and quantization endpoints were initially assumed to be job-placement rather than discovery; they are not — both are List...BackendsEndpoint returning "installed backends tagged X" for UI lists, i.e. identical semantics to /backends/available.

Deliberately not done

No compatible_nodes field on the response — GalleryBackend stays the gallery YAML type, and per-node install already exists via /api/nodes/:id/backends/install.

Known remaining gap (not addressed)

All three list endpoints also filter on b.Installed, which on a distributed controller comes from the controller's own empty filesystem. Fine-tune and quantization lists may still be short in distributed mode until installed-state aggregation is cluster-aware. Worth a follow-up issue.

Note for the merger

Please squash-merge. The two commits split accidentally: a git stash during the first commit's pre-commit gate reverted the staged source out from under it, so 1d9b7fe19 captured only the spec files and is red in isolation. The branch tip is correct and fully green. History was not rewritten to repair it, per this repo's rule requiring explicit approval for that.

Testing

ok  core/gallery                  16.498s
ok  pkg/system                     0.010s
ok  core/http/routes               0.322s
ok  core/http/endpoints/localai   31.539s
ok  core/services/worker           0.268s
ok  core/services/nodes          186.939s   (7 new registry specs)

make lint → 0 issues. Full pre-commit gate green.

---

🤖 Generated with Claude Code