Options

Every parameter has an evidence-backed default — Document.from_text(text) with nothing else is a complete call. This page is the full reference for when you want to tune something.

Naming across languages

Parameters are listed in Python style. Node uses the same names in camelCase (chunk_size → chunkSize); on fromFolder the chunking/retrieval options nest under an options object. Rust uses the same snake_case fields on LoadOptions / FolderOptions (each wrapped in Some(...), the rest ..Default::default()). The defaults and meanings are identical.

Document.from_text(text, ...)

Chunking (index-time — fixed at construction):

param	default	what it does
source	"document"	a label for the document
chunk_size	128	target tokens per chunk
chunk_overlap	1	sentences of overlap between adjacent chunks

Assembly (how the context is built from candidates):

param	default	what it does
strategy	"auto"	auto · reasoning_preserving · distractor_filtered · redundancy_pruned · max_density · raw_topk
token_budget	8192	default assembled-context budget (override per call)
candidate_k	20	how many candidates to retrieve before assembly

Retrieval (lexical by default; the rest only apply when retrieval="semantic" — see Retrieval options):

param	default	what it does
retrieval	"lexical"	"lexical" (BM25), "hybrid" (BM25 prune → dense rerank), or "semantic" (dense over every chunk)
model	None	name of a built-in embedding model to download — "bge-small" / "bge-base"
candidate_pool	50	hybrid only: BM25 prune depth before the dense rerank
rerank	None	optional cross-encoder second stage — "cross-encoder" (auto-downloaded) re-scores the candidate pool by jointly reading each (query, passage) pair. Works on any tier; off by default (details)

The rest are for bringing your own embedding model instead of model= (advanced — see Bring your own model):

param	default	what it does
embedder_model	None	path to a local embedding model
embedder_tokenizer	None	path to its tokenizer
embedder_dim	384	the model’s output dimension
embedder_pooling	"cls"	"cls" or "mean" (matches the model family)
embedder_query_prefix	None	query prefix for asymmetric models (E5: "query: ")
embedder_passage_prefix	None	passage prefix for asymmetric models (E5: "passage: ")

Document.from_chunks(chunks, ...)

Takes the same assembly and retrieval options as from_text — you’ve already chunked, so the chunking params don’t apply.

from_file / from_bytes / from_folder

The file loaders (Loaders) take all the same options. from_folder adds recursive, gitignore, ignore, persist, and index_dir — see from_folder.

doc.context(query, budget=None, neighbors=0, include_heading=False)

param	default	what it does
query	—	the question
budget	the doc’s token_budget	per-call budget override — query-time, no re-indexing
neighbors	0	also include the N adjacent chunks on each side of every selected chunk (same file) — see Structural expansion
include_heading	False	also include each selected chunk’s section heading

Also: doc.analyze(query) returns the same Decision Report without building a context (pure diagnostics), and doc.n_chunks / len(doc) (Node: doc.chunkCount; Rust: doc.len()) give the chunk count.

Structural expansion

A retrieved chunk often answers the question but drops you mid-section — the sentence before it set up the definition, the heading tells you which contract clause it is. neighbors= and include_heading= pull that structure back in, deterministically and with no model: they’re read straight from document order and headings.

Python

ctx = doc.context("what notice is required to terminate?", neighbors=1, include_heading=True)

Node.js

const ctx = doc.context("what notice is required to terminate?", undefined, 1, true);

Rust

let ctx = doc.context_expanded("what notice is required to terminate?", None, None, 1, true)?;

What makes this more than a ±1 hack is how it cooperates with the finite-attention core. A neighbor pulled in for continuity has little query overlap, so the normal distractor filter would throw it away. Instead, expansion chunks are justified by structure, not relevance — exempt from that filter, but still:

• bounded by the token budget (companions fill only leftover space after the real evidence is placed),
• deduplicated (overlapping windows merge),
• emitted in document order, so each hit reads as a contiguous window rather than scattered fragments,
• accounted for — they appear in ctx.citations (with their own heading/line) and as ctx.report.n_expanded, and the Decision Report prints a Structural expand: +N line.

Both default off, so plain context(query) is unchanged. Start with neighbors=1, include_heading=True for contracts/docs where surrounding context matters.

What context(...) returns

doc.context(query) returns a built context with everything you need to prompt a model and show your work:

on the result	what it gives
ctx.text()	the assembled context as one prompt string
ctx.chunks	the selected chunks’ text, in order
ctx.citations	provenance per selected chunk — {source, page, heading, line, text} (details)
ctx.report	the Decision Report — auto_decision, total_tokens, retained_evidence_ratio, …

Lower-level: redhop.build_context(query, chunks, ...)

Already have chunks and want to tune the assembly thresholds Document keeps fixed? The low-level API exposes them (Python; the same build_context / ContextConfig surface is re-exported from the redhop Rust crate):

param	default	what it does
strategy	"reasoning_preserving"	same strategy values as above
token_budget	8192	assembled-context budget
distractor_min_grounding	0.10	grounding bar below which a chunk is “junk”
link_min_jaccard	0.12	linkage at/above which a low-relevance chunk is rescued as a second hop
auto_passthrough_max_tokens	1500	auto: pass through at/below this size, prune above
redundancy_max_cosine	0.92	dedup threshold

analyze_context(...) and context_economics(...) give the diagnostics without assembling a context.

Next: Retrieval & context tips — the operational laws behind these defaults · Benchmarks — every number, reproducible.