Chunking strategies

A chunker decides what a retrieval unit is. Atrium ships five strategies, and the strategy that ran is stamped on every chunk — so a corpus with mixed strategies stays auditable, and a bad retrieval can be traced to the chunking that produced it.

The fiveCopy Anchor Link

baselineCopy Anchor Link

A sliding window over characters. The fastest path and the first thing to lose structure: a table gets cut in half, a heading ends up in the middle of a paragraph.

sentence_boundedCopy Anchor Link

Split on sentence boundaries, then pack the sentences up. Better than a sliding window for prose, and blind to everything that is not a sentence — a table is still a table of characters.

recursive_tokenCopy Anchor Link

Hierarchical: split into small pieces first, then merge the small pieces upward until a piece is big enough. The shape LangChain's recursive character splitter uses.

structure_aware — the defaultCopy Anchor Link

Respects the element types:

• a table is never split across chunks;
• a code block is never split across chunks;
• a heading rides on top of the chunks beneath it, as a breadcrumb in the embedding text, so a chunk retrieved from the middle of a section still knows where it came from;
• prose is merged up to the target size, and paragraphs that are too small to embed usefully are merged with their neighbour.

This is the default because it is the one that keeps a document's structure attached to the text you retrieve.

parent_childCopy Anchor Link

Produces two layers: wide parents for context and small children for retrieval. A child is what gets embedded and returned; its parent is fetched alongside it and returned too, so the caller can show the passage in its surrounding section.

Choosing oneCopy Anchor Link

autoCopy Anchor Link

auto is the default mode everywhere — in the API, the CLI and the config file. Today it resolves to structure_aware.

Adaptive selection — reading the document first and choosing a strategy per document — is on the roadmap and is not shipped. It is stamped roadmap on the site for the same reason.

Setting itCopy Anchor Link

Per request:

curl -X POST http://localhost:8000/ingest \
    -F "files=@./report.pdf" \
    -F "chunking_mode=precise"

From the CLI:

atrium ingest ./documents/ --chunking-mode structure_aware

PresetsCopy Anchor Link

Custom configurationCopy Anchor Link

atrium ingest ./documents/ \
    --chunking-mode custom \
    --chunking-config '{"target_chars": 900, "overlap_chars": 120}'

Or per request:

curl -X POST http://localhost:8000/ingest \
    -F "files=@./report.pdf" \
    -F "chunking_mode=custom" \
    -F 'chunking_config={"target_chars": 900}'

The configuration is validated strictly: an unknown key, a value of the wrong type, a number out of range, or an overlap larger than the target are all rejected with a 422 that names the field and the valid range. A typo in a chunking config fails loudly rather than silently falling back to a default.

Sizes are characters, not tokensCopy Anchor Link

The chunker measures in characters. There is no tokenizer dependency, which keeps the install small and makes the behaviour identical on every platform — but it means target_chars is not a token count. A rough conversion is four characters per token, and CHARS_PER_TOKEN_ESTIMATE is exposed if you want to reason about it.

Changing your mind laterCopy Anchor Link

Chunks are versioned by ingest run. Re-chunking a document replaces its previous chunks rather than mixing granularities in one collection — mixing them is a fast way to make retrieval worse.

atrium reingest ./documents/policy.md --doc-id policy --chunking-mode context_rich

POST /preview will show you the chunks a strategy produces before you commit to embedding them.