Full glossary

The ubiquitous language of indx. One entry per term, defining what the thing is; where a near-term exists, an Avoid line names it. Contracts live in packages/indx-interfaces; the protocol docs elaborate on each port.

The two stages

plan(): Stage one — cheaply observes an input and returns a serializable, explainable RoutePlan bound to a versioned capability snapshot. Planning never invokes expensive processing. Avoid: “decide” (the internal policy function that produces the plan, not the public stage).

encode(): Stage two — executes a supplied or freshly created plan, returning a block tree, embeddings, usage, and an execution trace. Execution may only use routes and fallbacks the plan already named. Note: “encode” has two other senses — VectorEncoder.encode() (produce vectors) and the POST /v1/encode HTTP operation. Unqualified, it means the stage.

embed(): Encodes a text or image query into a named embedding space. Query-side only; document vectors are produced during encode().

Source

Source: The declared input — a discriminated union of UriSource and InlineSource. What the caller says, not what was fetched. Avoid: input, document (a document is what a source turns out to contain).

LoadedSource: The internal working copy of an input: digest, media type, size, bytes. Private to indx-source; never crosses the wire. Avoid: “source snapshot” — snapshot belongs exclusively to capabilities.

source digest: The sha256:-prefixed content hash of the loaded bytes, minted by indx-source in the same pass that enforces the ceiling. A plan is bound to it; execution rejects a mismatch with 409. Avoid: checksum — that is the caller-supplied expected digest on a UriSource, whose mismatch is 422 checksum_mismatch.

input ceiling: The byte limit a deployment admits (limits.max_input_bytes, env INDX_MAX_INPUT_BYTES), enforced mid-stream by indx-source and advertised on the snapshot. Excluded from the snapshot hash.

media-type detection: Deciding what the bytes actually are: what an installed observer’s sniff recognizes, over the declared Content-Type, over the filename. indx-source owns the precedence and no table; which bytes are recognizable is a property of what is installed. Avoid: signature detection — that recognizes a document type, not a media type.

resolvable / plannable / routable: The three-way capability of an installation: resolvable — a loader fetches the URI scheme; plannable — an observer can look at the media type; routable (or readable) — a capability can run it. Each grows by installing a distribution; resolvable and plannable are excluded from the snapshot hash. A stock pip install indx resolves no scheme, recognizes no bytes and observes nothing.

Capabilities

capability: A unit of processing work with a stable, provider-neutral ID that routing refers to without depending on its package.

CapabilityKind: The enum a capability declares its role through: native_extraction, ocr, parser, model, embedder, manual_review. Policy routes over kinds, never capability IDs. Two members are deliberately off the ladder: a parser is reached only through signature nomination, an embedder only through a plan’s embedding_space_ids. Closed by decision, not a port: a kind is a policy position with a price and a fallback place, so an install adds none — work that is none of the six declares the nearest kind and the deployment corrects the numbers. Avoid: “lane” (informal; also double-booked by embeddings, see role / modality / lane).

CapabilityDescriptor: The lightweight public metadata for one capability: ID, version, kind, devices, media types, requirements, availability and unavailable_reason. Module scope stays cheap; the real engine loads in create().

capability snapshot: A deterministic, content-addressed inventory of capabilities, embedding spaces, limits, and the resolvable set that a plan is decided against. The snapshot ID is the content hash; limits and resolvable are deliberately excluded from it so installing a loader or observer does not invalidate outstanding plans. Avoid: registry (the snapshot is what the registry publishes, not the registry itself).

provider: The plugin-facing contract (CapabilityProvider): descriptors() advertises, create() lazily constructs the runtime implementation. May also declare source_observers() and source_loaders(). Avoid: EmbedderConfig.provider — a different sense, the model vendor string.

entry-point group: indx.capabilities — the importlib.metadata group through which installed distributions advertise providers. One group covers all three extension kinds (capabilities, observers, loaders).

registry: Discovers providers, validates declarations, rejects duplicate IDs, orders deterministically, mints the snapshot ID, and is the only path from a capability ID back to something that can run it.

builtin: Optional builtin = True flag on observers and loaders that indx ships. The registry orders installed ones ahead of builtins, so an extension can deliberately override a first-party format; claiming it can only cost precedence, never win it.

extras: Optional dependency sets gating heavy engines (--extra ocr, --extra vlm, --extra fastembed, --extra hosted). A missing extra surfaces as an unavailable descriptor and the ladder descends past it.

Device: cpu / gpu / external / manual. Drives the gpu_allowed and data_residency constraints; a hosted model is external. Closed like CapabilityKind, and where a capability offers several the router records the first of cpu, gpu, external, manual — a stated preference rather than the alphabetical accident it used to be.

Planning

RoutePlan: The durable, serializable plan artifact: plan_id, source_digest, media_type, capability_snapshot_id, policy_version, status, routes, signature matches, estimates. Avoid: “the route” (one plan holds many route assignments).

plan_id: Deterministic sha256: hash of the plan’s decided content, excluding plan_id and request_id — identical input, policy, and snapshot yield an identical plan. Avoid: request_id (the caller’s correlation ID, excluded from the hash) and the X-Request-ID header (per-response transport correlation) — three distinct identifiers.

routing ladder: The escalation order over CapabilityKind: native text layer → OCR → VLM → manual review. A rung is one step; every rung below the selected one stays in the plan as a fallback. The order and its membership are first-party; adding a rung is a POLICY_VERSION bump, never an install. Avoid: escalation chain, waterfall.

fallback: An ordered alternative candidate declared in the plan. Execution may use only the selected route or its declared fallbacks — never a silent re-plan. The terminal fallback is manual review, the only rung that cannot fail over.

manual review: The terminal rung (manual_review, device manual). Declares no media types because a human can read anything; an install that stripped it out answers 503 when the ladder is exhausted.

RouteAssignment / RouteCandidate: An assignment binds a scope to one selected candidate plus ordered fallbacks; a candidate is a capability ID, a device, and its decision reasons.

ScopeRef: Where a route applies: document, page (1-based), or region (ScopeKind). A plan has one document-scope assignment — the document default — plus a page override for each page that disagrees with it.

DecisionReason: The public explanation of a selection: a stable code (text_layer_usable, page_appears_empty, escalation_fallback, terminal_fallback, signature_match, …) plus human-readable detail.

PlanStatus: ready or unsatisfied. An unsatisfied plan lists unsatisfied_constraints and is reported (HTTP 200), not raised.

RoutingConstraints: The caller’s business constraints: minimum_quality, deadline_ms, maximum_cost_usd, gpu_allowed, data_residency, plus capability_ids (an allowlist; empty means the ladder decides) and fallbacks_allowed, which name the reader. data_residency refuses external devices.

policy version: POLICY_VERSION, stamped into every plan; bumped whenever the routing decision or the plan artifact changes.

economics: Per-kind routing inputs — quality, cost per page, latency per page — private to the router and overridable per deployment via INDX_ROUTING_ECONOMICS. They move the plan’s public estimates. Core-owned by decision: a descriptor declares no price, so a capability whose real cost differs from its kind’s default is admitted and estimated on the default until an operator corrects it. Avoid: actuals, usage (execution-side; see below).

admission: Whether a capability’s constraints leave it a device and a budget; the constraint names that ruled it out become unsatisfied_constraints.

Preflight and observation

preflight: The cheap, local, deterministic evidence-gathering stage before routing: no OCR, no model, no rendering, no network. “Preflight’s budget” is the standard observers and signature detectors are held to.

SourceObserver: The port producing cheap per-page evidence for a media type. It claims a media type by answering with evidence and disclaims by answering with an empty tuple (“not mine”); its media_types attribute is advertisement, never a dispatch gate. Installing one makes a media type plannable.

SourceLoader: The port fetching bytes behind a URI scheme, yielded in chunks. Unlike an observer, its schemes attribute is load-bearing: selection, 415 enumeration, snapshot advertisement. A loader never mints the digest and never enforces the ceiling — indx-source owns both.

PageEvidence: One page’s observation (1-based): text-layer state, open-string signals, optional RegionEvidence.

TextLayerState: usable_without_ocr / missing / unusable — the primary evidence the ladder’s first rung stands on.

signals: The shared open-string evidence vocabulary policy matches on: font, image, empty. They live in indx-interfaces so observers cannot drift; empty asserts an absence and carries a higher burden of proof. Open in form, closed in meaning: the ladder reads empty and the text-layer state and nothing else, so a signal an observer invents is inert rather than wrong.

PreflightContext: The whole-source preflight artifact (digest, page count, pages), private to the router — which is what stops an observer forging the identity a plan binds to. Observers return only PageEvidence.

signature detection: Opt-in per request: cheaply recognizing a document type (an invoice, a form) so planning can nominate a specialist.

signature nomination: A SignatureMatch placing its candidate_capability_id ahead of the generic ladder, never in place of it. A match whose capability is not installed is still reported but does not change the route; confidence is the share of independent signals matched, a signal counting in proportion when it is one, not a calibrated probability.

process chart (工程系統図): A manufacturing flow drawn with a symbol convention: a triangle is a material, an ellipse an operation, a diamond an inspection, two nested triangles an assembly; connectors between symbols are the steps, and a large rectangle groups one line’s steps. Recognized per slide by the process-chart signature and read by process-chart-parser into metadata.process_chart.

layout (DXF): What a CAD program shows as a page of a drawing: the model space and each paper-space layout, in tab order. indx-observer-dxf counts them as pages, the division the format states, the way a workbook’s sheets and a deck’s slides are.

Execution and output

Block: A node of the flat addressable output tree: ID and parent ID, kind, index, normalized bbox, text, embeddings, metadata, status, provenance.

BlockKind / ScopeKind: Two overlapping enums. BlockKind (document/page/region/chunk) is both the request-side ask in granularities and the response-side fact on a block; it was two enums under two names until Phase 3 folded them, since the executor was only ever translating one into the other. ScopeKind is where a route applies (no chunk), and stays separate because a route and a block are not the same thing.

BlockStatus: completed / unreadable / failed. A scope that could not be read is reported with a reason, never omitted; empty text is a completed read of a blank page — producing nothing at all is the failure. On a PageOutput the two non-completed values mean different things to the ladder: failed is the capability saying “try someone else” and descends, unreadable is a verdict about the content and is kept.

output validation: The executor’s check on what a rung produced, before the page counts as read: absent, declared failed, or a self-reported confidence under INDX_VALIDATION_MIN_CONFIDENCE. Any of the three sends that page alone to the next rung and discards the refused output. First-party by decision, not a port. Avoid: “quality gate” — nothing here measures output against ground truth.

confidence: Two different numbers under one word, kept apart by where they live. On a SignatureMatch it is a share of independent signals matched at plan time, a signal counting in proportion when it is one. On PageOutput.metadata (CONFIDENCE_METADATA_KEY) it is what a capability said about its own read, which reaches ExecutionActuals.quality and can fail the validation floor. Neither is a calibrated probability.

PageOutput: What one capability produced for one page. Deliberately not a Block: block IDs and the tree are the executor’s to mint.

PageReader: The runtime implementation create() returns for a reading capability — read(content, media_type, pages) — one protocol covering every reading kind.

ExecutionTrace: The record of every capability attempted per scope, including failures: planned vs actual capability, device, status, fallback_index, latency, cost. It is what makes a fallback visible.

actuals / usage: ExecutionActuals — measured latency, cost, quality, and device page counts for one execution; Usage — the aggregate bytes/pages/cost/latency rollup. cost and quality are both only ever what capabilities reported about themselves, and are 0.0 / null when none did. Avoid: estimates (plan-side, derived from economics).

provenance: Per-block record of which plan and which capability produced it. On the document block it also names media_type and the source_uri or filename the bytes arrived under. Avoid: metadata — that carries what a capability extracted (e.g. an invoice key) or what a caller supplied, not where the block came from. source_uri in provenance is a string echoing the request; the canonical Source is the declared input model above, and the two are not interchangeable.

document metadata: The document block’s metadata: the caller’s own labels supplied on EncodeRequest.metadata (owner, tenant, sensitivity), plus languages where a detector is installed, classification where the request enabled a classifier, and entities where it enabled an entity extractor. Carried, never enforced — who may read a vector afterwards is the index’s question. Avoid: ACL, policy — indx transports these labels and evaluates none of them.

language detector: LanguageDetector, the port asked with text a reader produced — never with bytes — for the languages it is written in. Installed like a chunker, advertised nowhere, and absent by default. Avoid: bare “detector” — that is the signature detector, which is a plan-time port over bytes. The two never appear under one word.

LanguageScore: One language a detector saw and how sure it was: a lowercase ISO 639-1 code and a [0, 1] number, ordered highest first under the languages metadata key. A self-report about characters on the same footing as CONFIDENCE_METADATA_KEY, never a claim about subject matter — that is a classifier’s.

classifier: DocumentClassifier, PageClassifier or ChunkClassifier — the ports asked with the full text of one document, page or chunk, for what that text is. Each carries an ID because a request enables it by name under EncodeRequest.classification, per unit; advertised on the snapshot outside the hash, in one namespace shared with the entity extractors. Avoid: signature detection — that is plan-time, over bytes, and nominates a parser. Avoid the bare “document classifier” for the family; that names one of the three.

facet: One question a classifier answers about a document — document_type, business_unit, industry — named by the classifier, enumerated by nothing in indx. The first enabled classifier with an opinion on a facet wins it.

LabelScore: One label a classifier gave a facet and how sure it was: a name and a [0, 1] number, ordered highest first per facet under the classification metadata key. A self-report calibrated only as far as the classifier says — a word-list ratio, an entailment probability, a model’s own number.

entity extractor: PageEntityExtractor or ChunkEntityExtractor, the ports asked with the text of one block for the names in it and where they are. Enabled by ID under EncodeRequest.extraction, per unit. Avoid: “NER” as a contract word — that is an implementation technique; the port is named for its unit and its return shape.

EntitySpan: One name an extractor found: the surface text, a [start, end) character range into the text of the block that names it, and a [0, 1] confidence on the same self-report footing as LabelScore. Avoid: byte offset — the range is characters, and in UTF-8 Japanese the two differ threefold.

enricher: DocumentEnricher, PageEnricher or ChunkEnricher, the ports asked with the full text of one document, page or chunk for what it says and what it is about. Enabled by ID under EncodeRequest.enrichment, per unit, in the one namespace the classifiers and extractors share. Avoid: “summariser” or “tagger” for the port; one enricher may give either part or both.

Enrichment: What an enricher answered: a summary, prose in the text’s own language, and tags, LabelScore entries whose vocabulary is the enricher’s own rather than a facet’s. Each part is optional, an absent part is no opinion, and each is won by the first enabled enricher with an opinion on it. Written under the enrichment metadata key on the document or page block, and under chunk_enrichment on the document block for chunks.

entity count: The document block’s aggregation under entities: how many times a (label, NFKC-normalized surface form) pair occurred, with the raw surface forms kept beside it. Avoid: identity, mention resolution — a count over a normalized string is not an identity, and nothing in indx resolves coreference.

chunk: The embeddable unit. Only chunk blocks carry document vectors; page and document blocks carry none.

Embeddings

EmbeddingSpace: A versioned declaration of vector dimension, metric, normalization, and the embedders forming it. One provider declares a whole space; two providers may not share a space ID.

embedder fingerprint: The content-addressed sha256: hash of an EmbedderConfig (vendor, model, revision, roles, modalities, preprocessing) — the string two installs compare to know their vectors are comparable.

role / modality / lane: EmbedderRole is document/query; EmbedderModality is text/image; each role×modality lane in a space must resolve to exactly one embedder. Note: “lane” is also used informally for capability kinds (“the OCR lane”) — in embedding context it always means role×modality.

DOCUMENT_EMBEDDING_MODALITIES: The modalities a run hands a document embedder, in preference order — (text, image). Text for a chunk that carries any, the rendered page for a chunk standing in for a page nothing could read as text. The single statement the router’s fault and the executor’s selection both read; a space declaring no document lane it covers embeds nothing. Query lanes are unconstrained by it.

VectorEncoder: What create() returns for an embedder-kind capability: one encode() for text and image alike.

Errors and transport

error envelope: The single typed failure shape: type, code, message, optional param, optional request_id. param is the dotted pydantic location of the failing field; a discriminated-union member carries its tag as a segment (source.uri.uri).

the three refusals: Installation-dependent, deliberately distinguishable: unsupported_source — no loader resolves the scheme (415); source_unreadable — no observer can look at the media type (422); source_forbidden — a loader’s guard refuses the destination (422).

Deadline: Monotonic expiry plus a cancellation flag, checked between units of work — never inside a capability call.

StrictModel: The public-contract Pydantic base: extra="forbid", strict=True, validate_assignment=True. Every wire type derives from it.

typed IDs: NewType string aliases (PlanId, CapabilityId, SourceDigest, BlockId, …) in indx_interfaces.ids — nominally distinct in signatures, plain strings on the wire.