Functional Specification

Users

Students and hobbyists with ordinary laptops, privacy-minded individuals, educators, developers using Ollama or llama.cpp, researchers comparing hardware, and teams who want evidence before choosing a local-AI setup.

Jobs to be done

  1. "Can this machine run this model?" Answered by fit with assumptions.
  2. "Is my local server up and really loopback?" Answered by probe and privacy.
  3. "How fast is my installed model here?" Answered by opt-in infer (cold vs warm runs).
  4. "What does this report actually prove?" Answered by evidence labels, verify and audit.
  5. "Give my coding agent safe instructions." Answered by install-skills.

Commands

CommandInputOutputSide effects
doctornonehardware profilenone (one nvidia-smi call if present)
fitcatalog JSON, optional profile JSONper-model fit tablenone
proberuntime, optional loopback endpointstatus, failure code, model listone GET to loopback
inferinstalled model name, runs, prompttiming samples, prompt hashup to 5 POSTs to loopback; model is loaded by the runtime
benchmarkruns, iterationsstatistics of a CPU loopCPU use for a short time
comparetwo sealed benchmark reportsratio, or refusalnone
privacyoptional endpointrule verdict, data inventorynone
auditoutput directoryaudit-report.{json,md,html} plus 15 per-artifact fileswrites files; opens a loopback test server briefly
verifyreport JSONseal match or mismatch (exit 1)none
install-skillsproject dir, IDE, --dry-runfiles written or plannedcreates files, never overwrites
servesealed report, env tokenlocal read-only APIlistens on 127.0.0.1
demooptional out dirsample reportswrites files

Report formats

Every report command can print --format json|md|html or write all three with --out. Existing files are never overwritten unless --force.

Fit model

required = weights x headroom(1.35) + overhead + KV cache where weights = parameters x bits / 8. KV cache is included only when kvBytesPerToken is supplied. Category possibly_fits means free RAM is at least the estimate; likely_insufficient_ram means it is not. With a detected NVIDIA GPU the report adds a single-GPU VRAM verdict. Speed and quality are always unknown.

Acceptance criteria (verified by tests)

Out of scope

Downloading or installing models/runtimes, hosted APIs, multi-user service, power measurement, model quality evaluation, leaderboard ranking.