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

# Native acceleration

> InferMap's optional compiled Rust/Arrow runtime — which components run native, the `INFERMAP_NATIVE` gate, and how parity is enforced. Generated from the native loader; do not edit by hand.

InferMap is pure-Python by default. An optional compiled kernel (Rust + PyO3/Arrow, crate `packages/rust/extensions/infermap-native`) accelerates the CPU-heavy components below. Under reference-mode the compiled path is the reference implementation and pure-Python is the byte-identical fallback — output is the same either way; native only changes wall-clock.

```bash theme={null}
pip install infermap[native]
```

## The gate

One env var, `INFERMAP_NATIVE`, read in `infermap/infermap/_native_loader.py`:

* `INFERMAP_NATIVE=auto` (default, or unset) — run native for any component whose kernel symbol is present on the loaded wheel, except the known-divergent components below.
* `INFERMAP_NATIVE=0` — force the pure-Python fallback everywhere.
* `INFERMAP_NATIVE=1` — require native; raise if the kernel isn't importable (the CI parity lane).

The kernel is discovered two ways, in order: the in-tree build `infermap._native` (local dev / parity lane), then the distributed `infermap_native._native` wheel (`pip install infermap[native]`). When neither is importable, every path runs pure-Python unchanged.

## Components

Each component maps to the native kernel symbol(s) its `auto` call site invokes (the *floor* symbol first — a component is native-capable when **any** listed symbol is present, so an older wheel stays wheel-skew safe). A ✓ in **Parity-signed** marks a component that cleared the byte-exact sign-off recorded in `_GATED_ON`.

| Component                | Kernel symbol(s)         | Parity-signed |
| ------------------------ | ------------------------ | ------------- |
| `detect_domain`          | `detect_domain`          | ✓             |
| `detect_identity_layers` | `detect_identity_layers` | ✓             |
| `exact_score`            | `exact_score`            | ✓             |
| `fuzzy_name_score`       | `fuzzy_name_score`       | ✓             |
| `initialism_score`       | `initialism_score`       | ✓             |
| `profile_score`          | `profile_score`          | ✓             |
| `pattern_match_types`    | `pattern_match_types`    | ✓             |
| `linear_sum_assignment`  | `linear_sum_assignment`  | ✓             |

## How parity stays honest

A component joins the native path only after a parity test proves its kernel is byte-identical (or integer-exact) to the pure-Python reference. CI runs a `INFERMAP_NATIVE=1` lane that builds the wheel and asserts native == pure-Python, and `scripts/check_native_symbols.py` reconciles the host's kernel references against the crate's `wrap_pyfunction!` exports so a referenced-but-unregistered symbol fails loudly. Because output is identical with or without the wheel, toggling the gate never changes a result — only speed.