[ihebChaaraoui]

Changelog title

Colibri: run large mixture-of-experts models

Changelog body

• Colibri is now the fourth engine PAIR can install, start, and route to. It serves large mixture-of-experts models by streaming experts from disk, so models that do not fit in memory can still run.
• Colibri's Add model list shows the models of Colibri's own setup list, then the open Hugging Face repositories tagged colibri, filtered to the architectures Colibri v2.1.0 can run.
• Model downloads land in ~/colibri-models, check free disk space first, resume after an interruption, and appear in the list only once complete.
• Load restarts Colibri on the chosen model and Delete removes its directory. Colibri serves one model per process, so it has no Eject.
• Colibri needs Python 3.10 or newer. Its installers are pinned to the v2.1.0 release and verified by SHA-256.

Bumps

• services: minor
• nvpair-cluster-manager: patch
• nvpair-engine-manager: minor
• nvpair-errors: patch
• nvpair-job-scheduler: patch
• nvpair-manual-nodes: none
• nvpair-node-info: patch
• nvpair-node-scanner: patch
• nvpair-node-settings: none
• nvpair-proxy: minor
• nvpair-tui: minor
• nvpair-ui-broker: minor
• nvpair-workload-manager: patch

Description

Colibri is an Apache-2.0
mixture-of-experts inference engine that streams expert weights from disk. It
makes a class of models usable on a single machine that PAIR could not serve
before: 20 GB to more than 1.5 TB checkpoints whose experts do not fit in memory
at once. This PR adds it as a fourth managed engine beside Ollama, LM Studio,
and llama.cpp.

A user can install Colibri from Engine settings, open Add model, pick one
of Colibri's own setup models or an open Hugging Face repository tagged
colibri, and let PAIR download it into ~/colibri-models. Load persists
the chosen model and restarts the server onto it; Delete removes that model
directory. Colibri serves one model per process, so the UI offers no Eject.
The engine listens on loopback 8001 behind PAIR's proxy facade on 8000, and
the proxy, broker, TUI, and inference dispatcher know its OpenAI and Anthropic
surfaces.

Most of the engine-manager work is generic rather than Colibri-specific: a
scan_dir model inventory for engines that keep one directory per model,
hf_snapshot downloads of open Hugging Face repositories with resume and a
free-space check, a {model} launch placeholder for single-model engines, a
manifest catalog with per-repository download rules, after_download steps,
and model_types so only architectures the pinned engine release runs are
offered. Colibri is the first manifest to use them.

Dependencies and Integrations

Current requirement. Ollama, LM Studio, and llama.cpp all need the model
weights to fit in RAM or VRAM. Colibri targets the models users ask for when
they do not: mixture-of-experts checkpoints whose inactive experts can stay on
NVMe. Without it, PAIR cannot install, list, download, or route to such a model
at all. No new Go or npm dependency is introduced; the engine is a JSON manifest
plus generic engine-manager primitives, and every download is performed by PAIR
itself.

License. Colibri and its release archives are Apache-2.0. Model
repositories keep their own licenses, which Hugging Face reports and the user
accepts there; PAIR only downloads repositories that are explicitly open.

Supported-version policy. The manifest pins Colibri v2.1.0 for each
platform that has a release: Windows x64 (base archive plus the CUDA archive),
Linux x64 (Vulkan), and macOS arm64 (Metal). Every archive is pinned by URL and
SHA-256 in manifests/colibri.json; PAIR verifies the hash before unpacking and
never upgrades an engine on its own. The manifest's model_types lists the
config.json values understood by that release's engine registry and must be
re-derived whenever the pinned release changes. Platforms without a v2.1.0
archive report Colibri as unavailable rather than falling back to a build from
source.

Validation boundary. Unit tests cover manifest validation, catalog
filtering, snapshot planning and resume, discard of unsafe paths, free-space
refusal, after-download steps, launch-model persistence, proxying, and the
desktop identity/capability tables, all against fake Hugging Face and process
fixtures; the suite makes no live download and starts no real engine. A real
install, download, and generation was not part of CI: it needs a machine with
enough NVMe for the chosen model and, for CUDA, a supported GPU. No performance,
quality, or hardware-compatibility claim is made here.

Maintenance plan. The engine is data, not code: a new Colibri release is a
manifest update (URLs, SHA-256 values, model_types, and any catalog changes) in
one reviewable PR, followed by the engine-manager suite. The colibri tag and
model_type fields on Hugging Face are the discovery contract; if upstream
renames or drops them, only the Colibri catalog source changes. If upstream
abandons the project, deleting manifests/colibri.json, the enum entry, and the
catalog source removes the engine without touching the other three.

Security implications. Install artifacts are pinned and hash-verified, and
only user-scoped installs are performed. Downloads only accept repositories
whose private and gated fields are explicitly false; no Hugging Face token
or credential is read or stored. after_download scripts are resolved inside the
frozen install directory, run with the model directory as their only argument,
and are bounded in time. Repository file names are rejected if they are
absolute, contain .., or would land outside the model directory. The engine
binds 127.0.0.1 on its own port and is reached through PAIR's proxy; model
prompts and responses are not logged.

Scope

Included: the Colibri manifest and catalog, the shared engine entry and
discovery key, the engine-manager model-store and download primitives, proxy,
broker, TUI, and inference-dispatcher support, the desktop engine identity,
capabilities, icon, welcome and model-hub handling, and the documentation and
rule updates that list the engines.

Excluded: the local sandbox/routing work in progress and the broker's
loopback-port fix; neither is part of this branch. services/versions.json and
CHANGELOG.md are untouched, as required.

Validation

Go 1.27.0, Windows x64, in a checkout of this branch:

# In services/shared, services/nvpair-proxy, services/nvpair-ui-broker,
# services/nvpair-tui, services/nvpair-job-scheduler, services/nvpair-node-scanner,
# services/nvpair-node-info, services/nvpair-workload-manager, services/nvpair-errors,
# services/nvpair-cluster-manager, services/nvpair-manual-nodes,
# services/nvpair-node-settings, and scripts/inference-dispatcher:
go build ./...
go vet ./...
go test -count=1 ./...

All pass. In services/nvpair-engine-manager, the same commands pass except for
two pre-existing Windows-only issues unrelated to this change:
TestRemoveTreePreserving_ReportsUndeletableEntriesAndRemovesOthers fails
because the test cannot make a file undeletable on this filesystem, and go vet
reports a lostcancel in install_artifacts_test.go, a file this PR does not
modify.

Desktop, from desktop/:

npm run typecheck:node
npm run typecheck:web
npm run test:unit
npm run lint
npm run service-contracts:check
npm run verify:build-scripts
node ../scripts/spdx-headers.mjs

typecheck:node, typecheck:web, lint, service-contracts:check, and
verify:build-scripts pass. The unit suite reports 283 passed and 2 skipped,
including engine-identity, proxy-engine-identity, model-catalog, and
match-downloaded-model. Its 15 failures are all in upstream's
mac-privilege-service.test.ts, which reports the macOS helper as unsupported
when the suite runs on Windows; that file is not touched by this PR. SPDX
reports 1103 files checked, 0 missing. Two local checks were inconclusive
because the checkout's node_modules did not match package-lock.json (a newer
Vitest and knip were installed): the test-project tsc pass and
dead-code:check. CI installs from the lockfile, where both are part of the
normal gate.

The cross-process services/tests suite was also run. It reached one failure,
TestWorkloadManager_BroadcastsLocalEventsToPeers, where the supervised
workload-manager could not bind its fixed port 14320; the test is unchanged
here and fails the same way when run alone. The other cross-process tests
passed.

The pull-request description validates with:

python scripts/release-intent/validate_pr.py \
  --description-file scratchpad/pr/colibri-pr.md \
  --skip-owned-files-check

Risk

• A new install path runs upstream release archives. Mitigated by pinned URLs
  and SHA-256 verification, user-scoped install, and explicit Python 3.10+
  probing before unpacking.
• Model downloads are large. PAIR checks free space before writing, resumes
  partial files, and only renames a complete .partial directory into place, so
  an interrupted pull never appears as a usable model.
• The shared engine enum and node-record service key gain a value. Older peers
  ignore the unknown key, and the existing engines keep their ports and
  behavior; Colibri reserves 8000/8001.
• Colibri needs Python 3.10 or newer on the machine. Install fails with an
  actionable message when it is missing, and the welcome screen does not
  preselect the engine.
• The first readiness check can take up to 600 seconds while a large model
  loads; this is scoped to Colibri's manifest.

Checklist

• I have read the Contributing Guidelines.
• Every commit is signed off (git commit -s), certifying the Developer Certificate of Origin.
• New or existing tests cover the change.
• Relevant documentation is updated.
• I checked the diff, changed filenames, and commit messages for credentials, private data, internal URLs, internal issue identifiers, and generated artifacts.
• I recorded the validation commands and results above.
• I declared version bumps in the release-intent block above. services/versions.json is written by automation; I did not edit it by hand.

🤖 Generated with Claude Code