[build] and [output]

[build] sets how the file's main vectors (space 0) and indexes are written. [output] sets which files come out, where they go, how much the manifest records, and where the embed cache lives. Both tables are optional.

[build]
preset = "hybrid"        # the default
with_graph = true

[output]
mode = "single"
dir = "out/handbook"
provenance = "standard"

[build]Copy Anchor Link

The keys are passed to the Python writer urna.build for every output file. They apply to space 0 only; named spaces take their precision from [[models]] space_dtype.

See presets and stored precision for what each costs in size and recall, and the build presets reference.

preset, dtype and mrl_dim are not checked when the spec is validated. urna.build rejects a bad value when it writes the file, which is after rows are loaded and every model has embedded them. The build then fails with a Python ValueError and exit 1, for example unknown preset: fast (expected exact|compressed|tiny|nano|hybrid) or mrl_dim must satisfy 0 < mrl_dim <= embedding_dim (256), got 512. Run a small --sample build first when you change them. The vectors stay cached, so the rerun after a fix does not embed again.

preset, dtype and mrl_dim change the stored vectors or the search contract, so they change the file's content_hash and every citation. The graph is not part of the content_hash: with_graph and graph_top_m leave citations unchanged.

[output]Copy Anchor Link

Validation errors (exit 2): output.mode: single|per-model|both, output.provenance: minimal|standard|full, and output.embed_media requires a [media] section (there is nothing to inline).

Output modesCopy Anchor Link

Every file carries the same chunks, the same space 0 and the same media tables, so all of them cite identically. There is one manifest and one lock per build, named after the corpus, whatever the mode.

ProvenanceCopy Anchor Link

provenance changes only <name>.manifest.json:

In standard, the home rewrite happens first, so a path under your home directory stays ~/... even when it lies inside the spec's directory. Relative paths and paths outside your home become relative to the spec's directory. The manifest fields are listed on build artifacts.

Cache rootCopy Anchor Link

Embeddings are cached outside the output directory, shared by every spec and output directory on the machine. The root is the first of:

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

A leading ~ expands. The location never enters the build lock, so builds that use different roots can still match. A root that cannot be created stops the build with spec error: output.cache_dir: cache root <path> is not a usable directory (...) (exit 2). The cache layout is on build artifacts.

The files a build writes are described on build artifacts.