urna doctor

urna doctor checks everything ask and retrieve depend on for potion corpora: the Python interpreter, numpy and tokenizers, the embedder script, the potion table, and one real offline embed of a probe string. It exits with the code of the first failing check, so scripts and installers can branch on the failure class. It makes no network request.

Unlike the other engine verbs, doctor runs Python: it starts the interpreter up to three times.

UsageCopy Anchor Link

urna doctor

OptionsCopy Anchor Link

ChecksCopy Anchor Link

The checks run in this order. Two of them stop the list, because the checks after them need what they found.

Check 7 runs only when check 4 passed; otherwise it shows as a warning, "skipped (python deps missing)".

Because the first failure decides the code, a machine with Python but without numpy exits 3 even when the embedder is also missing. Code 4 appears only when the interpreter already has both packages. No check looks at the Python version.

The interpreter, the embedder script and the table are found with the lookup orders in paths: URNA_PYTHON, then the venv urna setup builds, then the nearest .venv, then python3; and the repo layout first, then each data directory's urna/forge/. The table must sit next to the script that was found, in models/potion-base-8M/.

OutputCopy Anchor Link

urna doctor prints to stdout one line per check with a tag (ok, warn or fail(N)), then urna doctor: ok or urna doctor: failed. Every failure except 6 adds a hint line. On stderr it prints the chosen interpreter as [urna] embedder interpreter: <path>, and, when the probe failed, the embedder's error as embedder stderr: <text>.

Color is used only when stdout is a terminal, so piped output has no escape codes. NO_COLOR or URNA_COLOR=none turn it off on a terminal too.

A machine set up with urna setup:

urna doctor
[urna] embedder interpreter: /Users/nn/.local/share/urna/venv/bin/python
  ok       version: urna 0.5.1, format v1
  ok       simd: neon
  ok       python: /Users/nn/.local/share/urna/venv/bin/python (Python 3.12.14)
  ok       python deps: numpy, tokenizers
  ok       embedder: /Users/nn/.local/share/urna/forge/embed_query_potion.py
  ok       potion table: /Users/nn/.local/share/urna/forge/models/potion-base-8M/model.safetensors (30.2 MB)
  ok       embedder run: dim=256 model_hash=sha256:8f2eb91a754b4da59cdd8223d0ba196185fed1bb6f092fd2be0ff02b893b1c98
urna doctor: ok

An interpreter pinned to a path that does not exist:

urna doctor
[urna] embedder interpreter: /nonexistent/python
  ok       version: urna 0.5.1, format v1
  ok       simd: neon
  fail(2) python: not runnable: /nonexistent/python (set URNA_PYTHON, or run `urna setup`)
urna doctor: failed
  next: `urna setup` lays down the embedder and a python env

Exit codesCopy Anchor Link

urna setup ends with the same checks and returns the same codes when they fail; see urna setup.

In a repo checkout, the checkout's embedder always wins the lookup, so a git-lfs pointer there keeps failing with 5 no matter how often you run urna setup.

ExamplesCopy Anchor Link

Branch on the code in a provisioning script:

urna doctor > /dev/null 2>&1
case $? in
  0) echo "ready" ;;
  2|3|4) urna setup --yes ;;
  5) urna setup --yes --force ;;    # an embedder is present, so only --force replaces its table
  *) echo "embedder run failed: run urna doctor for the error" ;;
esac

Check a specific interpreter before pinning it:

URNA_PYTHON=/opt/py312/bin/python urna doctor

See the scalar SIMD warning (the exit code stays 0):

URNA_FORCE_SCALAR=1 urna doctor