Config reference

Every field of the configuration file, its default, and what it changes. See Write a config for how to use them together.

Top level

Field	Type	Default	Meaning
name	string	required	Lowercase letters, digits, ., -, _; 2 to 64 characters. Names the index directory, the calibration record and the report
corpus	path	required	Directory of source documents, resolved against the file's directory
golden	path	required	The golden set JSONL
description	string	""	Free text; excluded from the configuration hash

ingest

Field	Type	Default	Meaning
chunker.name	string	sentence_window	fixed, sentence_window or structure
chunker.params	mapping	{window: 6, overlap: 2}	Passed to the chunker's constructor
include	list	["**/*.md", "**/*.txt", "**/*.html", "**/*.pdf", "**/*.docx"]	Glob patterns to parse
exclude	list	[]	Glob patterns to skip

Chunker parameters: fixed takes size (800) and overlap (120) in characters; sentence_window takes window (6) and overlap (2) in sentences; structure takes none.

embedding

Field	Type	Default	Meaning
name	string	hashing	hashing, sentence_transformers or openai
params	mapping	{dim: 512}	hashing takes dim; the others take model

hashing is deterministic and needs no download, which is why it is what CI runs. sentence_transformers needs the local extra, openai the openai extra.

index

Field	Type	Default	Meaning
backend	string	numpy	numpy, faiss or qdrant
dir	path	.cairn/index	Parent directory; the index lands in <dir>/<name>
params	mapping	{}	Backend specific, for example a server URL

retrieval

Field	Type	Default	Meaning
mode	string	hybrid	dense, bm25 or hybrid
k	int 1 to 50	8	Passages handed to generation
candidates	int 1 to 500	40	Pulled from each index before fusion
rrf_k	int	60	Reciprocal rank fusion constant; larger flattens the influence of rank
rewrite.enabled	bool	false	Expand the question into several phrasings and fuse the results
rewrite.n	int 1 to 8	3	How many phrasings
rewrite.provider	component	generation provider	A cheaper model for rewriting
rerank	component	none	cross_encoder or lexical
rerank.enabled	bool	true	Present but disabled, for an ablation without deleting the block
rerank.top	int	candidates	How many candidates to rerank

generation

Field	Type	Default	Meaning
provider.name	string	stub	stub, ollama, openai or anthropic
provider.params	mapping	{}	For example {model: llama3.2}
max_tokens	int >= 16	600	Output cap per answer
temperature	float 0 to 2	0.0	Zero, so a run is reproducible
abstain_text	string	see below	The sentence an abstention returns

The documents do not support an answer to this question. The closest passages are attached.

calibration

Field	Type	Default	Meaning
alpha	float 0 to 1	0.10	Target error rate among answered questions
split	float 0 to 1	0.4	Share of the golden set held out to fit the threshold
seed	int	7	Fixes the stratified split
dir	path	.cairn/calibration	Where the record is written, as <dir>/<name>.json

judge

Field	Type	Default	Meaning
name	string	stub	stub (mechanical, free) or llm (the versioned rubric)
params.provider	component	generation provider	A dedicated judging model
params.model	string	provider default	Override the model

confidence

Field	Type	Default
name	string	weighted
params.w_retrieval	float	0.4
params.w_rerank	float	0.3
params.w_self	float	0.2
params.w_citation	float	0.1

Weights are renormalised over the signals actually present, so removing the reranker does not silently shrink the confidence scale.

budget

Field	Type	Default	Meaning
max_cost_per_question_usd	float	none	Recorded in the report's notes as cost_within_budget
max_p95_latency_ms	int	none	Recorded as p95_within_budget

Advisory. The enforcing comparison is the gate's.

Paths and identity

Relative paths resolve against the directory the configuration file lives in.

Derived locations:

Accessor	Value
corpus_dir()	<file dir>/<corpus>
golden_path()	<file dir>/<golden>
index_dir()	<file dir>/<index.dir>/<name>
calibration_path()	<file dir>/<calibration.dir>/<name>.json

content_hash() is a sha256 over the configuration with the paths, the description and the directories excluded, so the same experiment on two machines hashes the same. It appears on every report and every calibration record.

Shipped configurations

File	Retrieval	Embedder	Provider	Needs
default.yaml	hybrid	hashing	stub	nothing; what CI runs
bm25.yaml	bm25	hashing	stub	nothing
dense-hashing.yaml	dense	hashing	stub	nothing
hybrid-hashing.yaml	hybrid	hashing	stub	nothing
hybrid-local.yaml	hybrid, cross-encoder rerank	sentence_transformers	stub	local
hybrid-local-rewrite.yaml	as above, plus rewriting	sentence_transformers	stub	local
hybrid-ollama.yaml	hybrid, cross-encoder rerank	sentence_transformers	ollama	local, a local daemon
hybrid-openai.yaml	hybrid	openai	openai	openai, a key
hybrid-anthropic.yaml	hybrid, cross-encoder rerank	sentence_transformers	anthropic	local, anthropic, a key

The first four differ only in how candidates are combined, which is what makes them an ablation rather than a collection.