Check whether a model fits before downloading it

Now that we can load a model and unload it when we're done, there's a step worth taking before either one: asking whether the model is likely to fit in memory at all.

assessModelFit answers that question without downloading a single byte, loading a model, or running a native probe. It reads each candidate's generated catalog metadata against a fresh memory sample and returns one of three verdicts: likely-fits, likely-too-large, or unknown. Treat unknown as "can't say," not as a disguised no. It comes back when the catalog has no metadata for a model, the estimator hasn't been calibrated on this platform, or the evidence otherwise won't support a claim either way.

assessModelFit takes two more inputs that affect the verdict:

• execution: 'sequential' tells the SDK to treat every candidate as loaded in memory at once, matching what actually happens when models load one after another with none unloaded in between.
• policy: 'interactive-v1' withholds a slice of whatever memory is free right now (20%, capped at 2 GiB on desktop) so the verdict leaves headroom for the rest of the system, not just the model.

Pass both candidates in one call so their verdicts share a single memory budget:

const result = await assessModelFit({
  models: [
    { model: QWEN3_600M_INST_Q4, workload: { kind: "llm", contextTokens: 8192 } },
    { model: QWEN3_8_27B_MULTIMODAL_UD_Q8_K_XL, workload: { kind: "llm", contextTokens: 8192 } },
  ],
  execution: "sequential",
  policy: "interactive-v1",
});

const gib = (n: number) => (n / 1024 ** 3).toFixed(2);
if (result.budget) {
  console.log(`▸ Budget: ${gib(result.budget.availableAfterReserveBytes)} GiB free`);
}

for (const model of result.models) {
  console.log(`▸ ${model.name}: ${model.verdict}`);
}

console.log("▸ Combined verdict:", result.verdict);

Notice how QWEN3_600M_INST_Q4 comes back likely-fits on its own, but the combined verdict still comes out likely-too-large. Sequential execution keeps both candidates loaded in memory at once, so the oversized one drags the total down regardless of how small the other candidate is.

Note: assessModelFit is advisory only. It never blocks loadModel, reserves memory, or picks a model for us. We still decide what to do with a likely-too-large or unknown verdict.