data-cleaner-agent

data-cleaner-agent

エージェント型ワークフローで、乱雑な CSV をクリーンアップします。LLM がデータに必要なクリーンアップ手順を判断し、テスト済みの Python 関数が実際の処理を行います。モデルはクリーンアップを計画するだけで、データの値には一切触れません。そのため、値がでっち上げられたり、気付かないうちに書き換えられたりすることはありません。

すぐにオフラインで利用でき、API キーは不要です。LLM から操作できるほか、他の AI エージェントから MCP ツールとして呼び出すこともできます。

クリーンアップ前／後

Full Name , Country, Signup Date, Amount Paid          full_name    country  signup_date  amount_paid
 Alice  ,Netherlands,2023-01-05,"€1.200,50"                Alice  Netherlands   2023-01-05       1200.5
Bob,nederland,05/01/2023,"$900"              ─────▶          Bob  Netherlands   2023-01-05        900.0
 Alice  ,NL,2023-01-05,"€1.200,50"                         Carol      Germany   2023-02-10       1000.0
Carol , Germany ,2023-02-10,1000                             Dan      Belgium   2023-03-01        750.0
Dan,belgie,2023/03/01,"€ 750,00"

1 回の処理で、ヘッダーを修正し、空白を削除し、3 種類の日付形式を ISO 形式に変換し、€1.200,50／$900／€ 750,00 を数値に変換し、国名を標準化して、重複した Alice の行を削除しました。

インストールと実行

pip install agentic-csv-cleaner

clean-csv messy.csv cleaned.csv       # clean a file
clean-csv messy.csv                   # or just print the result

API キーは不要です。デフォルトのプランナーは、オフラインで動作する一連のヒューリスティックです。

仕組み

「エージェント型ワークフロー」とは、いくつかの要素で構成されるソフトウェアのことです。

   look at the data   ->   planner picks the steps   ->   run the steps   ->   report
                           (rules, or an LLM)             (tested code)

安全に信頼できる理由となる判断は、次のとおりです。

プランナーは、どの列にどのツールを実行するかを決めます。ツールが変換を行います。 言語モデルは判断（「この列は金額のように見える」など）は得意ですが、信頼できる計算は苦手です。そのため、LLM は決められたツールの中から操作を選ぶだけです。値を読み取って「クリーンアップ済み」の値を書き戻すことはありません。LLM によるデータクリーンアップで問題が起きるのは、たいていこの部分です。

2 種類のプランナー、1 つのループ

プランナー	内容	必要なもの
RuleBasedPlanner	簡単なデータプロファイルに基づくオフラインのヒューリスティックです。デフォルトで使用されます。	なし
LLMPlanner	プロファイルとツールの一覧を LLM に送り、JSON 形式のプランを受け取ります。	pip install "agentic-csv-cleaner[llm]" ＋ ANTHROPIC_API_KEY

どちらも同じ手順のリストを返すため、ループは変わりません。入れ替えるのは頭脳だけで、基盤部分はそのままです。

ログには各手順で実際に行われた処理が記録されます。変換によって結果をきれいにできなかった箇所（解析できない数値や日付、対応付けられないカテゴリなど）も含まれるため、正確な解析結果と確信に基づく推測を区別できます。

他のコードやエージェントから利用する

from cleaner.api import clean_csv_text

result = clean_csv_text(open("messy.csv").read())
print(result["cleaned_csv"])
print(result["steps"])

MCP ツールとして利用する（Claude Desktop）

他の AI エージェントからクリーナーをツールとして呼び出せるため、プロンプト内でトークン単位に CSV を再フォーマットするのではなく、適切にクリーンアップできます。手順は 3 つです。

1. インストールする

pip install "agentic-csv-cleaner[mcp]"

2. クライアントの設定に追加する（Claude Desktop の設定ファイルは macOS では ~/Library/Application Support/Claude/claude_desktop_config.json に、Windows では %APPDATA%\Claude\claude_desktop_config.json にあります）：

{
  "mcpServers": {
    "csv-cleaner": { "command": "python", "args": ["-m", "cleaner.mcp_server"] }
  }
}

3. Claude Desktop を再起動します。 エージェントから clean_csv ツールを利用できるようになります。このツールは CSV テキストを受け取り、クリーンアップ済みの CSV と、実行した処理のレポートを返します。

他の MCP クライアントで利用する

同じサーバーはどの MCP クライアントでも動作し、異なるのは設定だけです。コマンドは python -m cleaner.mcp_server です。

Cursor — ~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）。設定はホットリロードされます：

{ "mcpServers": { "csv-cleaner": { "command": "python", "args": ["-m", "cleaner.mcp_server"] } } }

VS Code / GitHub Copilot — .vscode/mcp.json。キーが異なり（mcpServers ではなく servers）、type が必須である点に注意してください。ツールは Copilot の エージェントモード でのみ実行されます：

{ "servers": { "csv-cleaner": { "type": "stdio", "command": "python", "args": ["-m", "cleaner.mcp_server"] } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json（存在しない場合は作成します）：

{ "mcpServers": { "csv-cleaner": { "command": "python", "args": ["-m", "cleaner.mcp_server"] } } }

Cline — VS Code の拡張機能にある MCP 設定パネルから追加します。

レポートの見方

このツールは、整ったデータを返すだけではありません。各手順で実際に行われた処理や、きれいな結果にできなかった箇所も知らせるため、正確な解析結果と確信に基づく推測を区別できます。

- coerce_numeric(amount): all 4 value(s) parsed cleanly
- standardize_dates(signup): 1/3 value(s) could not be parsed, set to null
- standardize_categorical(country): 1 value(s) not in the mapping, left unchanged: ['MARS']

そのため、値を黙って削除したり、間違ったカテゴリをそのまま残したりせず、問題を明らかにします。どのセルを確認すべきかが正確に分かります。

同梱内容

cleaner/tools.pyには、変換処理が含まれています：snake_case_headers、strip_whitespace、 coerce_numeric、standardize_dates、standardize_categorical、drop_duplicate_rows。

standardize_datesを例に見てみましょう。2023-01-05（年が先で、月が中央）と05/01/2023（日が先）では、 異なる解析ルールが必要です。全体に適用する設定を1つにすると、どちらかの形式が正しく処理されないため、このツールは値ごとに判定します。日付の形式が混在していると、本当に曖昧なケースもあります。このツールは推測せず、そうしたケースを明示的に処理します。

テスト

python -m unittest discover -s tests

ライセンス

MIT。