> ## 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.

# InferMap overview

> An inference-driven schema mapping engine that aligns messy source columns to a target schema with confidence scores and reasoning.

InferMap maps messy source columns to a known target schema, with a confidence score and a human-readable reason for each mapping. It runs in Python and TypeScript, and the two implementations are verified bit-for-bit against a shared golden-test suite.

## Install

<CodeGroup>
  ```bash pip theme={null}
  pip install infermap
  ```

  ```bash npm theme={null}
  npm install infermap
  ```
</CodeGroup>

Python database extras: `infermap[postgres]`, `infermap[mysql]`, `infermap[duckdb]`, `infermap[all]`. The TypeScript package requires Node 20+ and is edge-runtime compatible.

<Note>
  **Native acceleration.** The scorers + domain detection share a pyo3-free Rust
  core (`infermap-core`). Install `infermap[native]` to auto-dispatch to the
  compiled kernels — byte-identical output (CI parity-gated), governed by
  `INFERMAP_NATIVE` (`auto` / `1` / `0`). The TypeScript package runs the same
  kernels via an opt-in WASM backend (`enableInfermapWasm()`); the MCP
  `infermap://scorer-info` resource reports the active backend.
</Note>

## Quickstart

```python theme={null}
import infermap

result = infermap.map("crm_export.csv", "canonical_customers.csv")
for m in result.mappings:
    print(f"{m.source} -> {m.target}  ({m.confidence:.0%})")

# Apply the mapping to a DataFrame
import polars as pl
df = pl.read_csv("crm_export.csv")
renamed = result.apply(df)

# Save and reload
result.to_config("my_mapping.yaml")
saved = infermap.from_config("my_mapping.yaml")
```

In TypeScript:

```typescript theme={null}
import { map } from "infermap";

const result = map(
  { records: [{ fname: "John", lname: "Doe", email_addr: "j@d.co" }] },
  { records: [{ first_name: "", last_name: "", email: "" }] },
);

for (const m of result.mappings) {
  console.log(`${m.source} → ${m.target}  (${m.confidence.toFixed(2)})`);
}
```

## Key features

* **7 built-in scorers**: exact, alias, initialism, pattern-type, profile, fuzzy-name, and LLM (pluggable).
* **Optimal 1:1 assignment** via the Hungarian algorithm.
* **Common-prefix canonicalization** that strips schema-wide prefixes (for example `prospect_City` versus `City`).
* **Confidence calibration** (identity, isotonic, or Platt) into probabilities.
* **Domain dictionaries** for healthcare, finance, and ecommerce.
* **Custom scorers** via the `@infermap.scorer` decorator (Python) or `defineScorer()` (TypeScript).
* **Many input formats**: CSV, JSON, in-memory records, database tables, and schema definition files.
* **Edge-runtime compatible** with a minimal-dependency TypeScript core (only `goldencheck-types` for domain packs).
* Accuracy benchmark: 162 test cases, F1 0.84 (Python); TypeScript parity within 0.0005.

## CLI

| Command                                                                      | Purpose                                               |
| ---------------------------------------------------------------------------- | ----------------------------------------------------- |
| `infermap map <source> <target>`                                             | Map two files or schemas and print a report.          |
| `infermap apply <source> --config <mapping> --output <file>`                 | Apply a saved mapping to rename columns.              |
| `infermap inspect <source>`                                                  | Extract and display a schema from a file or DB table. |
| `infermap validate <source> --config <mapping> --required <fields> --strict` | Validate a saved config against a source.             |

```bash theme={null}
infermap map crm_export.csv canonical_customers.csv -o mapping.json
infermap apply crm_export.csv --config mapping.json --output renamed.csv
infermap inspect "sqlite:///mydb.db" --table customers
```

## Custom scorer

```python theme={null}
import infermap
from infermap.types import FieldInfo, ScorerResult

@infermap.scorer("prefix_scorer", weight=0.8)
def prefix_scorer(source: FieldInfo, target: FieldInfo) -> ScorerResult | None:
    if source.name[:3].lower() != target.name[:3].lower():
        return None
    return ScorerResult(score=0.85, reasoning=f"Shared prefix '{source.name[:3]}'")
```

## Scorer weights

The default pipeline (`default_scorers()`) is the six scorers below. `LLMScorer` is
**not** in the default set — it is opt-in (and stubbed until you wire a provider).

| Scorer            | Weight | Default? |
| ----------------- | ------ | -------- |
| ExactScorer       | 1.0    | yes      |
| AliasScorer       | 0.95   | yes      |
| InitialismScorer  | 0.75   | yes      |
| PatternTypeScorer | 0.7    | yes      |
| ProfileScorer     | 0.5    | yes      |
| FuzzyNameScorer   | 0.4    | yes      |
| LLMScorer         | 0.8    | opt-in   |

## Config

```yaml theme={null}
domains:
  - healthcare
  - finance
scorers:
  ProfileScorer:
    enabled: false
  FuzzyNameScorer:
    weight: 0.3
aliases:
  order_id:
    - order_num
    - ord_no
```