Paths and resolution order

This page lists every place urna reads from or writes to outside your corpus files, and the order in which it searches. The orders are the ones the code implements; when a lookup behaves unexpectedly, urna doctor prints what it found.

Data directoriesCopy Anchor Link

Every command that needs the embedder payload, the build tool or the setup venv searches these data directories, in order. Each one is expected to hold an urna/ directory. Unset or empty variables are skipped, and a directory equal to the one before it is dropped.

1. $URNA_DATA_DIR
2. $XDG_DATA_HOME
3. $HOME/.local/share, also when XDG_DATA_HOME is set
4. %LOCALAPPDATA%, read on every operating system
5. <directory of the urna binary>/../share

The last entry lets an unpacked release archive work with a share/urna/forge tree placed next to its bin/.

Install rootCopy Anchor Link

urna setup and urna setup --uninstall write to one directory, the install root. It is resolved from the current environment each time:

1. $URNA_DATA_DIR
2. on Windows only, %LOCALAPPDATA%
3. $XDG_DATA_HOME
4. $HOME/.local/share

Setup never writes to the binary-relative share/: the package manager that installed the binary owns it. With none of these set, the payload step is blocked and --uninstall fails with "no data dir (set URNA_DATA_DIR)".

The one-liner installers pick their directories the same way:

What lives in a data directoryCopy Anchor Link

The temporary files sit at the top level of the install root, next to urna/, not inside it.

On a default Linux or macOS install the data directory is ~/.local/share/urna (or $XDG_DATA_HOME/urna); on Windows it is %LOCALAPPDATA%\urna.

Script lookupCopy Anchor Link

The query embedders and the build tool are Python scripts. The binary looks for each one in this order and takes the first that exists:

1. The repo layout, python/<dir>/<script>, under the working directory, then under its parent, then under the checkout of a dev-built binary (a binary at <repo>/target/<profile>/urna whose <repo> has a python/ directory).
2. <root>/urna/<dir>/<script> for each data directory, in order.
3. Otherwise the relative path python/<dir>/<script>, which then fails as "not found".

Only the first script ships, so on an installed binary the others resolve only from a repo checkout. --embedder on ask, retrieve and search-text bypasses the lookup.

Because the repo layout comes first, running urna from inside a checkout uses the checkout's scripts and table, even when a payload is installed. urna doctor shows the path it picked.

Interpreter lookupCopy Anchor Link

The query embedders and the build tool run under one Python interpreter, chosen in this order:

1. $URNA_PYTHON, used verbatim.
2. The setup venv: the first data directory whose urna/venv/bin/python (urna\venv\Scripts\python.exe on Windows) exists.
3. .venv/bin/python in the working directory or one of its three parents.
4. python3 from PATH.

The choice is printed to stderr as [urna] embedder interpreter: <path> (not inside the explorer or during setup).

Step 3 runs the nearest .venv it finds, by position in the filesystem alone. In a directory tree you do not trust, set URNA_PYTHON so no discovered interpreter runs.

On Windows, step 3 looks for the Unix layout (bin/python), so it never finds a Windows .venv\Scripts\python.exe, and python3 is usually absent from PATH. Run urna setup or set URNA_PYTHON.

Embed cacheCopy Anchor Link

urna build caches embeddings and model probes under one root, shared across specs:

1. --cache-dir on the command line
2. [output] cache_dir in the spec
3. $URNA_CACHE_DIR
4. ${XDG_CACHE_HOME:-~/.cache}/urna

The cache key and invalidation rules are in reproducible builds and build artifacts.

Model directoriesCopy Anchor Link

Registry models (used by urna build and the registry query embedder, both in a checkout) are loaded from the first of:

1. an explicit model path: model_path in the spec's [[models]] at build time, --model-path on ask and retrieve
2. $URNA_MODEL_DIR_<NAME>, for example URNA_MODEL_DIR_WEMM_2B
3. the preset's own local directory, when it exists
4. for the wemm and jina presets, the Hugging Face cache snapshot that refs/main points to (under $HF_HOME/hub, default ~/.cache/huggingface/hub)

Nothing is downloaded unless URNA_ALLOW_DOWNLOAD=1. See the model registry.

The pip wheelCopy Anchor Link

The wheel carries its own copy of the potion table inside the package, at <site-packages>/urna/models/potion-base-8M. urna.potion_model_path() returns that path. The wheel reads no data directory and uses no setup venv.

All variables named here are described in environment variables.