people-enrichment

人材のエンリッチメントと検索（People Data Labs）

Person および Company データセットに対する5つのサブコマンドを備えた、scripts/enrich.py という1つのスクリプトです。すべてのサブコマンドで、APIキーの処理、ブール値で返されるPIIに基づく連絡先の判定、ステータスフラグ、.xlsx のスタイル設定、--dry-run による事前確認モードを共通して使用します。

サブコマンド	入力	出力	課金
person-enrich	氏名が指定された人物のリスト	プロフィール＋職歴	一致1件につき1クレジット
person-identify	人物のリスト（特定が曖昧）	スコア付き候補を複数表示	PDLの識別条件に応じて課金
person-search	条件フラグ	条件に一致する人物のリスト	返されたレコード1件につき1クレジット
company-enrich	企業のリスト	企業情報	一致1件につき1クレジット
company-search	条件フラグ	条件に一致する企業のリスト	返されたレコード1件につき1クレジット

2つの search コマンドは 結果 ごとにデータを返すため、コストは --size に応じて増加します。大規模な検索の前には必ず概算コストを伝え、ユーザーから追加の要望がない限り、--size は小さく設定してください（1リクエストあたり最大100件）。

対象範囲と振り分け

正当かつ相応な目的で、PDLによる人物や企業のエンリッチメント、または検索をユーザーが希望する場合に、このスキルを使用します。LinkedInを直接スクレイピングしたり、侵襲的なプロフィールを作成したり、ホスト環境で別のデータプロバイダーが必須とされている場合には、使用しないでください。

LinkedInスクレイパーではなくPeople Data Labsを使う理由

LinkedInのスクレイピングは不安定で、法的リスクもあります。このスキルでは、LinkedInをリアルタイムでスクレイピングするのではなく、ライセンスを受けたアグリゲーターとしてPDLを使用します。ユーザーがリアルタイムのスクレイピングを強く希望する場合は、スクレイパーを作成するのではなく、トレードオフについて説明してください。

APIキー

scripts/enrich.py はPDLキーを必要とします。実行時には次の順序で解決されます：PDL_API_KEY 環境変数 → カレントワーキングディレクトリの .env → スクリプトと同じディレクトリの .env。このスキルやスクリプトにキーを記述してはいけません。 キーがない場合、ライブコマンドは手順を表示して終了します。--dry-run と --self-test にキーは必要ありません。

.env はローカルでのみ作成してください：

echo 'PDL_API_KEY=their_key_here' > .env

.env は秘密情報として扱ってください。表示、コミット、アップロードはしないでください。--self-test はオフラインで実行され（サンプルデータを使用し、キーは不要）、サンプルの人物シートと企業シートを書き出します。これにより、クレジットを消費する前に出力形式を確認できます。

ドライランによる事前確認

クレジットを消費する前、特に大きなファイルや検索を扱う場合は、同じコマンドを --dry-run 付きで実行してください：

python scripts/enrich.py person-enrich --input people.csv --output out.xlsx --dry-run
python scripts/enrich.py person-search --company "Northwind Capital" --title director --size 25 --dry-run
python scripts/enrich.py company-search --industry "real estate" --country singapore --size 50 --dry-run

ドライランでは、入力や検索条件を検証し、予定される出力を表示して、最大クレジット数を見積もります。PDL_API_KEY は不要で、PDLへの呼び出しや .xlsx 出力の書き込みも行いません。

連絡先フィールドと無料プラン

無料プランでは、PDLはPIIフィールド（emails、phone_numbers）を値ではなくブール値で返します。true は連絡先情報が存在するものの、有料プラン限定であることを示し、false は登録情報がないことを示します。人物シートでは、これが Email status／Phone status 列に表示されます。値は included（実際の値あり。Proプラン）、exists - upgrade to view（有料プラン限定だが情報あり）、none on file、unknown のいずれかです。

5 つのコマンド

person-enrich — 名前を指定して人物を 1 対 1 で照合します。

python scripts/enrich.py person-enrich --input people.csv --output out.xlsx

認識される入力列（大文字・小文字や空白は区別しません）：name/full name、first name、last name、company/employer、title、location、email、linkedin/profile。行ごとの情報が多いほど、マッチ率が高くなります。

person-identify — 1 件のエンリッチ結果が曖昧な場合に、候補セットを取得します。

python scripts/enrich.py person-identify --input people.csv --max-candidates 5

入力は enrich と同じです。出力には、入力した人物ごとに複数の行が含まれ、それぞれにスコア付き候補（Match score 列）が表示されます。ユーザーはそこから正しい候補を選択できます。

person-search — 名前のリストを用意せず、条件で人物を検索します。

python scripts/enrich.py person-search --company "Northwind Capital" --title director --size 25

フラグ：--company --title --location --country --industry --name、および --size（1～100）、--dataset（デフォルトは all）、詳細に制御するための生の PDL SQL クエリを渡す --sql。フラグは AND 条件で組み合わされます。

company-enrich — 企業リストを企業属性データに照合します。

python scripts/enrich.py company-enrich --input companies.csv --output firms.xlsx

認識される入力列：name/company、website/domain、ticker、linkedin/profile、location/country/region/locality。行ごとに name/website/ticker/profile のいずれか 1 つ以上が必要です。

company-search — 条件で企業を検索します。

python scripts/enrich.py company-search --industry "real estate" --country singapore --min-employees 50 --size 50

フラグ：--name --industry --country --locality --tag --min-employees、および --size と --sql。

出力をユーザーと確認する

人物シートには 2 つのタブがあります。People（人物ごとに 1 行で、ステータスは色分け）と Employment history（過去の職務ごとに 1 行）です。企業シートには Companies タブが 1 つあります。最初に確認するのは Status 列です。matched（緑）、needs_review（琥珀色）、no_match（赤）、error（オレンジ）で示されます。ユーザーが再確認すべき行が分かるよう、琥珀色と赤の行は明確に伝えてください。

マッチの調整

--min-likelihood N（1～10）は、enrich/identify コマンドの信頼度の下限です。名前や企業名が一般的で、誤マッチよりも見逃しを選ぶ場合は値を上げ（6～8）、情報が豊富で網羅性を高めたい場合は値を下げてください。企業のエンリッチでは website/domain があると最も信頼性が高く、人物のエンリッチでは名前とあわせて企業名またはメールアドレスがあると最も信頼性が高くなります。

後からプロバイダーを切り替える

PDL 固有の部分は、*_params ビルダー、pdl_request、parse_person / parse_company マッパーです。別のプロバイダーに対応するには、その API に合わせてこれらを実装し、同じレコードの辞書形式を維持してください。入力の解析、ステータスの判定、SQL/フラグの処理、ドライランの概要表示、.xlsx の書き込みはそのまま使用できます。

原則

• 助言ではなく下書き — 出力は人が確認するための調査補助であり、確定的な判断ではありません。
• 決して作り出さない — PDL が返した情報のみを提示します。身元を推測するのではなく、no_match / needs_review を正直に示してください。
• 重要な処理は決定論的に — 入力の解析、ステータスの判定、ドライランの見積もり、.xlsx の書き込みは決定論的です。
• 誠実さと適切な調整 — 信頼度の低いマッチにフラグを付け、概算のクレジット費用を事前に示してください。
• ワークスペースの整理 — ユーザーが想定する場所に出力を書き込みます。スキル内のディスクに API キーを書き込むことは決してありません。

データの取り扱い

PDL はサードパーティであり、エンリッチ時には実際の氏名・企業名が送信されます — 名前自体が検索キーであるため、トークン化できません。.env / PDL_API_KEY は秘密情報として扱い、表示、コミット、アップロードを決して行わないでください。人物情報については、正当かつ適切な目的であることを確認し、その目的に関連するフィールドのみを収集してください。

注意点

1. 無料プランでは連絡先の値が表示されない — メールアドレスや電話番号はブール値として返されます。ステータス列を確認してください。
2. 検索コストは --size に応じて増加する — 概算のクレジット費用を伝え、--size は控えめにしてください。
3. 一般的な名前は誤マッチしやすい — --min-likelihood を上げるか、コンテキスト列（企業名・メールアドレス）を追加してください。
4. .env を決してコミットしない — キーは秘密情報です。--self-test と --dry-run にはキーは不要です。
5. ドライランは見積もり — 実際の請求は、PDL のエンドポイントの利用条件と、返されるレコードやマッチに従います。

確認チェックリスト

• 個人情報の補完／検索について、正当で相応な目的が確認されています。
• 大きなファイルや検索では、対象範囲を検証しクレジット数を見積もるために --dry-run を使用しています。
• ライブ実行用に、環境変数または .env から PDL_API_KEY を利用できます（スキルには絶対に書き込みません）。
• 大規模な検索の前に、おおよそのクレジット費用を明示しています。
• アンバー／赤のステータス行をユーザーに知らせています。
• .env を表示／コミットしていません。

要件

• Python 3.8+
• pip install openpyxl（HTTP には標準ライブラリの urllib を使用するため、requests は不要です）
• ライブ API 呼び出し用の PDL_API_KEY（環境変数または .env）。https://www.peopledatalabs.com で取得できます。
• PDL API へのネットワークアクセス。--self-test と --dry-run は完全にオフラインで実行できます。