> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insight.nobly.dk/llms.txt
> Use this file to discover all available pages before exploring further.

# How the classification tree runs

> What happens when the AI walks the classification tree: stepwise decisions, quoted evidence, confidence scoring, self-checking, and keyword extraction.

## Why a tree

Asking one AI prompt to pick between fifty document types and read thirty keywords in a single
step is unreliable: the model has too many options, and a mistake is invisible. The
classification tree replaces that with a series of **small, controlled decisions** — at each
level the AI chooses between a handful of clearly described branches, and every decision leaves
evidence you can inspect.

The tree also acts as a contract: its branches are the *complete* set of document types the AI
may suggest. A document that fits none of them gets no suggestion instead of a bad one.

## The walk, step by step

<Steps>
  <Step title="Read the document">
    The document's text is extracted — scanned files are OCR'd in natural reading order, so
    letterheads and headings come first — up to the configured
    [page cap](/document-classification/configuring-the-tree#max-pages).
  </Step>

  <Step title="Choose a branch">
    At each level the AI sees the beginning of the document plus the names and *when to choose*
    descriptions of the branches at that level — nothing else. It must pick one branch or answer
    **"None of the above"**, and it must quote the evidence from the document that justifies the
    choice, with a confidence.
  </Step>

  <Step title="Descend until a leaf">
    The chosen branch's own sub-branches are offered next, and so on, until the walk reaches a
    branch with no children. Along the way the walk collects each branch's extraction
    instructions and notes the document type stamped on the path.
  </Step>

  <Step title="Extract keywords">
    One extraction call reads the document against the stamped type's keyword configuration,
    guided by the main extraction prompt plus every instruction collected down the path, and
    restricted to the path's [allowed keywords](/document-classification/configuring-the-tree#allowed-keywords).
    Extracted values that must come from a keyword dataset are then matched against it.
  </Step>
</Steps>

## Evidence and grounding

Every classification step must quote text from the document as its justification. The quote is
verified against the extracted text (tolerating OCR noise such as a heading the scanner read
twice): a quote that cannot be found is flagged on that step as **not found in the document** in
the confidence tooltip. The flag does not change the score — OCR noise breaks verbatim matching
far more often than the AI invents a line — but a flagged step is the first place to look when a
classification surprises you.

## Confidence

The walk's confidence is the confidence of its **weakest step** — a classification is only as
strong as the shakiest decision on its path. One situation additionally caps it at 50%: a
**halted walk**, where the tree stamped a type but none of the more specific sub-branches
matched — the sub-branches contradict the confident choice one level up.

## Halted walks and the automatic re-walk

A **halt** is the tree's built-in self-check. It happens when the AI picks a branch that stamps a
document type, but then answers "None of the above" for every sub-branch below it — the branch's
own children refuse to corroborate the choice. In practice this usually means the first decision
was a near-miss between two similar branches rather than a genuinely unusual document.

Because of that, a halt triggers **one automatic re-walk** of the same text:

* The re-walk finishes **confidently** (on any branch) → its result is used. The near-miss heals
  itself and you never see it.
* The re-walk halts on the **same branch** → the document genuinely belongs there but fits no
  sub-category. The suggestion is kept, honestly capped at 50%.
* The re-walk halts **somewhere else** → the tree cannot agree with itself. No suggestion is
  made at all; a document the tree cannot place twice in a row should be indexed by a person.

<Tip>
  If the same kind of document repeatedly lands in the wrong branch, the fix is almost always
  sharper *when to choose* descriptions on the two branches being confused — including what a
  branch is **not** for. See
  [writing branch descriptions](/document-classification/configuring-the-tree#writing-good-branch-descriptions).
</Tip>

## Keyword extraction details

* **Instructions accumulate.** The tree's main extraction prompt applies to every document; each
  branch's instructions are added as the walk passes through it. The extraction call at the leaf
  sees all of them — so put general rules at the root and specifics on the branches.
* **Dataset matching.** A keyword backed by a dataset gets its extracted value matched against
  the dataset's entries, guided by the configurable
  [matching guidance](/document-classification/configuring-the-tree#dataset-matching-guidance). Ambiguous
  matches are surfaced for you to resolve rather than silently picked.
* **Cascading keywords.** When a child keyword's options depend on a parent keyword, the
  suggested parent value scopes the child's options. If the parent could not be determined, the
  child falls back to validating against its full dataset instead of being dropped.

## Throughput

Analyses run a few at a time per environment: dropping many files at once queues them internally
rather than firing everything at the AI service simultaneously. A large batch finishes gradually,
row by row.