InferMap

移転しました。 このリポジトリは benzsevern/goldenmatch モノレポの packages/python/infermap (and packages/typescript/infermap)/ に移転しました。このリポジトリはアーカイブされています。新たな開発はモノレポで行われます。

infermap

推論駆動型スキーママッピングエンジン。
扱いにくいソース列を既知のターゲットスキーマに、正確かつ説明可能に、設定不要でマッピングします。
Ben Severn が開発しました。

📖 Wiki · 🌐 ドキュメント · 🧪 サンプル · 💬 ディスカッション · 🐛 問題報告

---

infermap はスキーママッピングエンジンです。任意の2つのフィールドコレクション（CSV、DataFrame、データベーステーブル、メモリ内レコード）を渡すと、信頼度スコアと人が読める説明を添えて、どのソースフィールドがどのターゲットフィールドに対応するかを判断します。PyPI の Python パッケージとnpm の TypeScript パッケージとして利用でき、マッピングの判断は共通のゴールデンテスト同等性スイートによってビット単位で検証されています。

目次

• インストール
• クイックスタート
• 仕組み
• 機能
• どのパッケージを使えばよいですか？
• カスタムスコアラー
• CLI の例
• 設定リファレンス
• ドキュメント
• ライセンス

インストール

Python

pip install infermap

オプションのデータベース用エクストラ：

pip install infermap[postgres]   # psycopg2-binary
pip install infermap[mysql]      # mysql-connector-python
pip install infermap[duckdb]     # duckdb
pip install infermap[all]        # all extras

TypeScript / Next.js

npm install infermap

コアエントリーポイントの実行時依存関係はありません。Next.js Server Components、Route Handlers、Server Actions、Edge Runtime に標準で対応しています。詳細については、パッケージの README を参照してください。

クイックスタート

Python

import infermap

# Map a CRM export CSV to a canonical customer schema
result = infermap.map("crm_export.csv", "canonical_customers.csv")

for m in result.mappings:
    print(f"{m.source} -> {m.target}  ({m.confidence:.0%})")
# fname -> first_name  (97%)
# lname -> last_name   (95%)
# email_addr -> email  (91%)

# Apply mappings to rename DataFrame columns
import polars as pl
df = pl.read_csv("crm_export.csv")
renamed = result.apply(df)

# Save mappings to a reusable config file
result.to_config("my_mapping.yaml")

# Reload later — no re-inference needed
saved = infermap.from_config("my_mapping.yaml")

TypeScript

import { map } from "infermap";

const crm = [
  { fname: "John", lname: "Doe", email_addr: "[email protected]" },
  { fname: "Jane", lname: "Smith", email_addr: "[email protected]" },
];

const canonical = [
  { first_name: "", last_name: "", email: "" },
];

const result = map({ records: crm }, { records: canonical });

for (const m of result.mappings) {
  console.log(`${m.source} → ${m.target}  (${m.confidence.toFixed(2)})`);
}
// fname       → first_name  (0.44)
// lname       → last_name   (0.48)
// email_addr  → email       (0.69)

Next.js では、Route Handler にそのまま組み込めます。設定不要で Edge Runtime 上でも動作します。

// app/api/infer/route.ts
import { map } from "infermap";
export const runtime = "edge";

export async function POST(req: Request) {
  const { sourceCsv, targetCsv } = await req.json();
  const result = map({ csvText: sourceCsv }, { csvText: targetCsv });
  return Response.json(result);
}

仕組み

各フィールドのペアは、7 つのスコアラーで構成されるパイプラインを通ります。各スコアラーは [0.0, 1.0] のスコアを返すか、判定を保留します（None／null）。エンジンは加重平均（少なくとも 2 つのスコアラーが必要）でスコアを統合し、ハンガリーアルゴリズムを使って最適な一対一の割り当てを行います。

スコアラー	重み	検出する内容
ExactScorer	1.0	大文字と小文字を区別しない、完全な名前の一致
AliasScorer	0.95	既知のフィールド別名（fname ↔ first_name、tel ↔ phone）とドメイン辞書
InitialismScorer	0.75	略語形式の名前（assay_id ↔ ASSI、confidence_score ↔ CONSC）
PatternTypeScorer	0.7	サンプル値から判定するセマンティック型 — email、date_iso、phone、uuid、url、zip、currency
ProfileScorer	0.5	統計的プロファイルの類似性 — dtype、null 率、unique 率、長さ、カーディナリティ
FuzzyNameScorer	0.4	正規化されたフィールド名に対する Jaro-Winkler 類似度（共通プレフィックスの正規化を含む）
LLMScorer	0.8	プラグイン可能な LLM ベースのスコアラー（デフォルトではスタブ）

エンジンは共通プレフィックスの正規化も適用し、prospect_ のようなスキーマ全体に共通するプレフィックスを自動的に除去します。そのため、City と prospect_City は City と City として比較されます。また、任意の信頼度キャリブレーションにより、割り当て後の生スコアをキャリブレーション済みの確率に変換します（実データにおける ECE は 0.46 から 0.005 に改善）。

アーキテクチャの詳細を読む →

機能

	Python	TypeScript
組み込みスコアラー 7 種	✅	✅
ハンガリー法による割り当て	✅ (scipy)	✅ (vendored)
カスタムスコアラー	@infermap.scorer	defineScorer()
ドメイン辞書	✅ (YAML)	✅ (inlined)
信頼度キャリブレーション	✅ (Identity/Isotonic/Platt)	✅
スコア行列の確認	✅	✅
メモリ内データ	Polars、Pandas、list[dict]	Array<Record>
ファイルプロバイダー	CSV、Parquet、XLSX	CSV、JSON
スキーマ定義ファイル	YAML + JSON	JSON
データベースプロバイダー	SQLite、Postgres、DuckDB	SQLite、Postgres、DuckDB
エンジン設定	YAML	JSON
保存されるマッピング形式	YAML	JSON
CLI	✅ (Typer)	✅ (node:util)
DataFrame への適用	✅	❌ (CLI 経由で CSV を書き換え)
エッジランタイム対応	❌	✅
実行時依存関係ゼロ	該当なし	✅
精度ベンチマーク	✅ (162 ケース、F1 0.84)	✅ (差は 0.0005 以内)

機能の完全な対応表 →

どのパッケージを使うべきですか？

目的	使用するパッケージ
Python のデータパイプラインまたはノートブックを構築する	Python
Next.js アプリ、Node サービス、またはブラウザツールを構築する	TypeScript
サーバーレスのエッジ関数でマッピングを実行する	TypeScript（Node 組み込み機能への依存なし）
コマンドラインでアドホックに CSV を調査する	Python CLI のほうが機能豊富、TS CLI のほうが軽量
Python バックエンドと Next.js 管理 UI の両方を使う	両方 — JSON 設定形式を介して出力に互換性があります

v0.3 の新機能

実データで F1 が +18.3pp 向上。4 つの改善を組み合わせた結果です。

v0.2 baseline    F1 0.657
+ min_conf 0.2   F1 0.765  (+10.8pp — empirically tuned threshold)
+ prefix-strip   F1 0.821  (+5.6pp  — City vs prospect_City now works)
+ InitialismScorer F1 0.840 (+1.9pp  — ASSI, CONSC, RELATIT now work)

新機能：

• ドメイン辞書 — MapEngine(domains=["healthcare"]) を使用すると、ドメインに合わせて厳選された別名が読み込まれます。組み込みドメイン：generic（デフォルト）、healthcare、finance、ecommerce。詳細は examples/09_domain_dictionaries.py を参照してください。
• 信頼度のキャリブレーション — MapEngine(calibrator=cal) を使用すると、生のスコアがキャリブレーション済みの確率に変換されます。組み込みのキャリブレーター：IsotonicCalibrator、PlattCalibrator。Valentine の ECE：0.46 → 0.005。詳細は examples/10_calibration.py を参照してください。
• InitialismScorer — 略語形式の列名を照合します（assay_id ↔ ASSI）。ChEMBL の F1：0.524 → 0.819。
• 共通プレフィックスの正規化 — ファジーマッチングの前に、prospect_、assays_ などを自動的に削除します。
• Valentine コーパス — 精度テスト用の Valentine ベンチマークから、実際のスキーママッチング事例を 82 件収録しています。
• 完全な TypeScript 対応 — すべての新機能を移植しました。TypeScript のテストは 186 件。ベンチマークの F1 は Python との差が 0.0005 以内です。

カスタムスコアラー

Python

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]}'")

from infermap.engine import MapEngine
from infermap.scorers import default_scorers

engine = MapEngine(scorers=[*default_scorers(), prefix_scorer])

TypeScript

import { MapEngine, defaultScorers, defineScorer, makeScorerResult } from "infermap";

const prefixScorer = defineScorer(
  "prefix_scorer",
  (source, target) => {
    if (source.name.slice(0, 3).toLowerCase() !== target.name.slice(0, 3).toLowerCase()) {
      return null;
    }
    return makeScorerResult(0.85, `Shared prefix '${source.name.slice(0, 3)}'`);
  },
  0.8 // weight
);

const engine = new MapEngine({
  scorers: [...defaultScorers(), prefixScorer],
});

CLI の例

CLI はどちらのパッケージでも同じように動作します。

# Map two files and print a report
infermap map crm_export.csv canonical_customers.csv

# Map and save the config (Python: --save, TS: -o)
infermap map crm_export.csv canonical_customers.csv -o mapping.json

# Apply a saved mapping to rename columns
infermap apply crm_export.csv --config mapping.json --output renamed.csv

# Inspect the schema of a file or DB table
infermap inspect crm_export.csv
infermap inspect "sqlite:///mydb.db" --table customers

# Validate a saved config against a source
infermap validate crm_export.csv --config mapping.json --required email,id --strict

設定リファレンス

どちらのパッケージもエンジン設定（スコアラーの重みの上書きと別名の拡張）を受け付けます。Python は YAML、TypeScript は JSON を使用しますが、構造は同一です。

# Python: infermap.yaml
domains:
  - healthcare
  - finance
scorers:
  LLMScorer:
    enabled: false
  FuzzyNameScorer:
    weight: 0.3
aliases:
  order_id:
    - order_num
    - ord_no

// TypeScript: infermap.config.json
{
  "scorers": {
    "LLMScorer":       { "enabled": false },
    "FuzzyNameScorer": { "weight": 0.3 }
  },
  "aliases": {
    "order_id": ["order_num", "ord_no"]
  }
}

注釈付きの完全なリファレンスは infermap.yaml.example を参照してください。

ドキュメント

• 📖 Wiki — 両言語の完全なリファレンス
  • はじめに
  • Python API
  • TypeScript API
  • Python と TypeScript の比較 — 移行ガイド
  • スコアラー
  • アーキテクチャ
  • FAQ
• 🌐 ドキュメントサイト
• 🧪 例
  • Python の例 — 基本的なマッピング、データベース、カスタムスコアラー、設定、ドメイン辞書、キャリブレーション、スコア行列の詳細な確認を扱う番号付きスクリプト 10 件
  • TypeScript の例 — 基本的なマッピング、Next.js Edge Runtime、カスタムスコアラー、データベース、ドメイン辞書、保存と再利用
• 📓 Colab で開く — Python ノートブック
• 💬 GitHub Discussions
• 🐛 Issue トラッカー

作者

Ben Severn

ライセンス

MIT