parallel-data-enrichment

データのエンリッチメント

エンリッチ：$ARGUMENTS

開始する前に

行数や指定されたフィールド数によっては、エンリッチメントに数分かかる場合があることをユーザーに伝えてください。

任意：出力列を提案する

ユーザーの意図が曖昧で（「これらの企業に役立つ情報を追加して」など）、追加する列がわからない場合は、実行を開始する前に API に提案を求めてください。

parallel-cli enrich suggest "Find CEO and recent funding info" --json

応答は {title, processor, enriched_columns, warnings} というエンベロープです。enriched_columns 配列だけを取り出し（エンベロープ全体ではありません）、enrich run の --enriched-columns の値として渡します。これは --intent の代わりに指定します。これらのフラグは、エンリッチする内容を指定する別々の方法です。suggest が processor を返した場合は、run の呼び出しで --processor を明示的に渡してください。ユーザーがすでに希望するフィールドを指定している場合は、このセクションをスキップしてください。

enrich suggest には parallel-cli ≥ 0.3.0 が必要です。このコマンドだけが使えない場合は、任意の提案手順をスキップし、手順 1 では --intent を使用してください。Setup に従って、インストール方法に応じたアップグレードを提案してください。認証、API、無効な入力に関するエラーを、古い CLI が原因だと判断してはいけません。intent ベースの実行では、それ自体が提案をリクエストします。明示的に列を指定した場合は core-fast がデフォルトになりますが、--processor で上書きしない限り、intent によって別のプロセッサが選択されることがあります。

手順 1：エンリッチメントを開始する

以下のコマンドパターンのいずれか 1 つを使用してください（ユーザーの実際のデータに置き換えます）。

インラインデータの場合：

parallel-cli enrich run --data '[{"company": "Google"}, {"company": "Microsoft"}]' --intent "CEO name and founding year" --target "output.csv" --no-wait --json

CSV ファイルの場合：

parallel-cli enrich run --source-type csv --source "input.csv" --target "output.csv" --source-columns '[{"name": "company", "description": "Company name"}]' --intent "CEO name and founding year" --no-wait --json

以前の調査タスクのフォローアップで、その interaction_id がある場合は、コンテキストの連鎖を追加してください。

parallel-cli enrich run --data '...' --intent "..." --target "output.csv" --no-wait --json --previous-interaction-id "$INTERACTION_ID"

これにより、前のタスクのコンテキストが再利用されます。Zero Data Retention（ZDR）アカウントではコンテキストの連鎖を利用できないため、その場合はフラグを省略し、必要なコンテキストを明示的に含めてください。エンリッチメントでは新しい interaction_id は返されません。後続のフォローアップに備えて、前のタスク ID を保持してください。taskgroup_id や Search／Extract の session_id は、タスクの interaction_id ではありません。

重要： コマンドがブロックせず、すぐに戻るように、必ず --no-wait を指定してください。

--json の出力から taskgroup_id、url、num_runs を直ちに保存してください。interaction_id フィールドはありません。作成が中断された場合や応答が失われた場合は、別の実行を送信する前にグループが作成済みかどうかを確認してください。直ちに次の内容をユーザーに伝えてください。

• エンリッチメントを開始したこと
• 進行状況を確認できるモニタリング URL

グループはサーバー側で実行されます。保存した ID を使って、後からポーリングを再開できます。

手順 2：結果をポーリングする

実行ごとに永続的な出力パスを選んでください（例：enrichment-acme-tgrp-<id>.json）。ポーリングは出力ファイルを上書きするため、既存のファイルがあれば内容を確認し、置き換える意図がない限り新しいパスを使用してください。拡張子に関係なく、出力は JSON です。input と output または error を含む行の配列が返されます。非同期ポーリングには basis や行ごとの interaction ID は含まれません。引用やコンテキスト ID を捏造してはいけません。

parallel-cli enrich poll "$TASKGROUP_ID" --timeout 60 --output "enrichment-<descriptive-name>-<group-id>.json"

重要：

• ポーリング回数には上限を設けてください。--timeout 60 を指定すると、待機の合間に進行状況を確認できます。
• 手順 1 の --target は、--no-wait モードでは使用されません。結果の保存先を決めるのは、ここで指定する --output だけであり、ファイルは常に JSON 形式です。
• 完了したグループにも、失敗した行が含まれることがあります。output を含む行と error を含む行を別々に数え、その合計を num_runs と比較してください。ファイルが空、または不完全な場合、入力全体のエンリッチメントが成功したとは言えません。

ポーリングがタイムアウトした場合、または中断された場合

タイムアウトの終了コード 5 または中断によって、ローカルでの待機は終了します。まだ実行中だと伝える前に、グループの状態を確認してください。

parallel-cli enrich status "$TASKGROUP_ID" --json

is_active、status_counts、num_runs を確認してください。アクティブなグループの場合は同じポーリングを再開し、非アクティブなグループの場合は結果を取得して、失敗した行や未解決の行を報告してください。タイムアウトを理由にグループを作り直したり、失敗した行を自動的に再実行したりしてはいけません。ローカルでのファイル書き込みに失敗した場合は、同じグループ ID を使い、書き込み可能な出力パスを指定して再試行できます。

ユーザーが CSV をリクエストした場合

保存した JSON をローカルで別の CSV に変換します。重複行や失敗行も含め、元の入力列と行をすべて保持してください。エンリッチメントフィールドは、名前が競合する入力フィールドとは分け、失敗行にはエラー列を含めてください。ストリーミングされた行が元の入力順と一致すると決めつけたり、行の識別が曖昧な場合に結合方法を推測したりしないでください。行数を検証し、入力 CSV は変更しないでください。これはローカルでの変換であり、非同期ポーリングで生成された CSV ではありません。JSON と CSV の両方のパスを報告してください。

応答形式

ステップ 1 の後： 進捗を確認できるモニタリング URL を共有してください。

ステップ 2 の後：

1. 成功、失敗、合計の行数を報告し、結果が欠落している場合は明示してください。
2. 成功した行を数件、代表的な失敗があればその例もプレビューし、すべての行が成功したかのように伝えないでください。
3. 出力ファイルの絶対パスをユーザーに伝えてください。

完了後は、モニタリング URL を繰り返すのではなく、保存した出力へのリンクを記載してください。

セットアップ

parallel-cli が見つからない場合は、インストールして認証します。

/parallel:parallel-cli-setup

ドキュメントに記載されたオプションやコマンドが見つからない場合は、インストール方法を特定し、その方法でアップグレードしてください。単体版は parallel-cli update、pipx は pipx upgrade parallel-web-tools、uv は uv tool upgrade parallel-web-tools、Homebrew は brew upgrade parallel-web/tap/parallel-cli、npm は npm update -g parallel-web-cli を実行します。再試行する前に、エージェントのターミナルでバージョンとヘルプを再確認してください。

認証エラーまたは API エラーの場合は、返されたメッセージを確認してください。403 は権限、アカウントポリシー、または請求に関する問題を示している可能性がありますが、残高不足を証明するものではありません。必要に応じて parallel-cli auth --json とその authenticated ブール値を確認し、認証情報は公開しないでください。残高を確認するのは請求に固有のエラーがある場合に限り、資金の追加には明示的な確認が必要です。保存済みのグループ ID は再利用し、作成結果が曖昧な場合は自動的に再試行しないでください。