How It Works
From cheap observation to an executed, traceable document representation.
indx separates deciding from doing. The router can inspect a source without invoking OCR, a vision model, or an embedding model. The executor then follows the declared decision without silently replanning it.
Dashed nodes are extension points: loaders, observers, capabilities, chunkers, and embedding spaces all arrive from installed distributions through the indx.capabilities entry point — see Extend indx.
1. Observe cheaply
Section titled “1. Observe cheaply”The source loader bounds input size, determines media type, calculates a digest, and inspects page-level evidence. For PDFs, preflight distinguishes usable text layers, images, drawings, and empty pages without paying for recognition.
2. Decide against a snapshot
Section titled “2. Decide against a snapshot”plan() chooses only capabilities recorded in a content-addressed snapshot. A route has a document default, page overrides where needed, and an ordered fallback ladder. The plan records:
- the selected capability and device for each scope;
- public reasons for every selection and fallback;
- estimated quality, latency, and cost;
- source digest, media type, policy version, and capability snapshot ID; and
- any constraint that made a valid route impossible.
Optional signature detection lets a specialist nominate itself, for example an invoice parser. The generic ladder remains behind it. A mistaken nomination costs an attempt, not the document. The ladder, nomination, and the other ways a capability enters a route are laid out in Routing.
3. Execute without changing the decision
Section titled “3. Execute without changing the decision”encode() can create a plan or accept one produced earlier. When a plan is supplied, the executor verifies the source digest, media type and snapshot and may run only the selected capability or fallbacks already listed in that plan.
Fallback happens per outstanding page. Pages already read successfully are retained. Only unread pages descend to the next capability. The result contains an addressable document/page/chunk block tree, provenance, an event for every attempted capability, and actual usage.
4. Keep failures visible
Section titled “4. Keep failures visible”Unreadable and failed scopes remain in the block tree with a reason. Manual review is the terminal rung in the default policy. The system never turns an unread page into an apparently successful but incomplete document.