Skip to main content

Optional extras: probing and borrowing

Status: implemented. backend/extras.py answers whether an optional extra is usable here; backend/modules/network/borrow.py decides whether work needing one runs locally, on a friend's machine, or not at all.

  • Probe: backend/extras.py (probe, available, snapshot)
  • Routing: backend/modules/network/borrow.py (route, acquire, capability)
  • Consent: the compute lease — see network

Why this exists​

This repo has several uv sync --extra … groups, and some are genuinely painful to install: voice pulls torch (1–2 GB), llamacpp builds llama.cpp from an sdist and needs cmake plus a C++ compiler, browser-engine fetches ~150 MB of Chromium, clip downloads ~350 MB of weights on first use.

Nothing automatic may run a plain uv sync. A plain sync makes the venv match the core dependency set exactly, uninstalling every extra. pnpm dev:desktop (scripts/dev-desktop.mjs) and the desktop supervisor's startup repair (apps/desktop/src/backend.ts) both did, so each desktop launch silently removed voice, clip, llamacpp… right after the user installed them. Both now run uv sync --inexact, which installs what is missing and removes nothing. By hand, name every extra you want in one command (uv sync --extra voice --extra clip).

A laptop that lacks them should be able to borrow the desktop in the next room that has them — and that starts with being able to ask the question in one shape. Before this, every extra answered differently: karaoke.downloader.available() and library.clip.clip_installed() returned a bare bool, llamacpp.trace_runner.available() returned (bool, reason), and the voice services were lazy imports turned into a 503 at the route. None of them could say the third thing.

Three states, not two​

The rule hardware exists to enforce, applied here:

stateavailablecertainmeaning
installedtruetrueit imported
absentfalsetrueImportError — genuinely not here
unknownfalsefalsepresent but would not load, or we could not look
The third row is the whole point

A native library that fails to load is not the same fact as a package that was never installed. Reporting it as "not installed" sends someone to reinstall a package already sitting on disk, and they will find the reinstall changes nothing.

So an ImportError is the only exception read as absence. Anything else — a missing DLL, an OSError from a data file, a broken wheel — is reported as what it was, with the error attached.

An extra name the code does not declare is also certain: false: that is our bug, not the user's environment, and it must not render as "you have not installed this".

Probes import in this process, which is cheap (the package is imported, not used) and gives a real reason rather than a subprocess that dies two seconds after the user clicks something. Results are cached per process; reset_cache() exists for tests and for after an install.

extras.py deliberately decides no policy. Whether an absent extra means a 503, a disabled setting, or a request to borrow a peer's is the caller's business.

The borrow-or-hint rule​

probe locally
├── available → run locally
├── absent + a peer has it + lending arranged → run there
└── otherwise → the install hint, now naming the borrow attempt

Two things it will not do, and both are the interesting half:

"Could not ask" never routes to a peer. An extra that is installed but failing to load is a broken local install — a problem the user can actually fix. Quietly answering it by shipping their audio to a friend's machine hides it. Only a certain absence is grounds for borrowing.

Nothing is silently remoted. Every result says which node produced it (ranOn on the voice routes), the same way get_embeddings returns a method so callers can refuse to persist a fallback. A borrowed transcript that looks local is how a user comes to believe their laptop has Whisper installed.

A peer that declines is an answer, not an error: acquire turns a refused lease into an unavailable route carrying the reason, because the caller's job is to do the work or explain why it cannot.

borrow.capability() contributes an extras capability listing only what is installed, which is what makes network.find_peers able to answer "who can transcribe this?".

Absent extras are not advertised — that would make a peer's UI offer something every request against it would refuse. Neither are uncertain ones, which would be worse: it would send a friend's work to a machine whose own install is broken.

Probe the module the extra actually installs​

ExtraSpec.modules must name modules the extra's own dependencies provide. This sounds obvious and was wrong for voice from the start: it probed for a module named whisper, but the extra installs torch, transformers and edge-tts — STT is openai/whisper-tiny.en run through transformers, and the openai-whisper package has never been a dependency (it appears nowhere in uv.lock).

Because every module in the tuple must import, voice reported available=False, certain=True — "it is genuinely not here" — on a machine with the whole extra installed, and told the user to run the uv sync --extra voice they had already run. It also meant a node with working speech never advertised voice to its peers, and would try to borrow one.

The failure mode is quiet in both directions, so when adding an extra, check the probe against the installed distribution rather than the feature's name.

Which extras are borrowable​

extralease serviceborrowable
voicevoiceyes
clipclipyes
llamacpptraceyes
browser-enginebrowseryes
geoip, webrtc—no: properties of this node's own networking
games-native—no: renders frames for a local pane
ffmpeg, yt-dlp—no: probed, but local-only

Borrowable extras are HTTP routes on the backend rather than separate processes, so they resolve to the same address through the tunnel. The lease service is what the authorizer checks, so holding one of them does not grant the others.