migrate-to-parallel

Parallel への移行

プロバイダーとの境界を、エンドツーエンドで置き換えます。HTTP レスポンスが成功した時点を完了ではなく中間地点と捉え、リクエストの構築、レスポンスの利用側、依存関係、設定、テスト、運用上の動作を移行します。

<skill-root> は、この SKILL.md が置かれているディレクトリとして解決します。現在の作業ディレクトリにかかわらず、同梱の参照資料とスクリプトはすべてそのディレクトリを基準に解決します。スキャナーは Python 標準ライブラリのみを使用します。Python 3.9 以降を利用できない場合は、ハーネスのファイル検索ツールを使って同等のリポジトリ検索を行い、同梱のスキャンを実行しなかったことを明記します。

適切な参照資料を読み込む

1. リポジトリに Exa が含まれている場合は、references/exa.md を読みます。
2. リポジトリに Tavily が含まれている場合は、references/tavily.md を読みます。
3. リポジトリに Perplexity Search、Sonar、Agent API の Web ツール、または Perplexity の検索ラッパーが含まれている場合は、references/perplexity.md を読みます。
4. リポジトリに Firecrawl の Search、Scrape、Batch Scrape、Extract、Agent、Research Index、Crawl、Map、Parse、Browser、Interact、Monitor、または MCP の利用が含まれている場合は、references/firecrawl.md を読みます。
5. いずれかの呼び出しが Search にルーティングされる可能性がある場合、またはクエリ、フィルター、鮮度、モード、結果リストの移行が必要な場合は、references/parallel-search.md を読みます。
6. いずれかの呼び出しが Extract、Chat、Task、エンティティ検出にルーティングされる可能性がある場合、またはストリーミング、構造化出力、引用が必要な場合は、references/parallel-products.md を読みます。
7. クエリが動的に生成される場合、プロバイダーがモデルツールとして公開されている場合、プロバイダーのレスポンス型が複数のモジュールに渡って使用される場合、またはアプリケーションで全コンテンツや合成された回答が必要な場合は、references/integration-patterns.md を読みます。
8. 検出された SDK、ラッパー、パラメーター、レスポンスフィールドのうち、これらの参照資料で扱われていないものについては、現行の公式ドキュメントを確認します。プロバイダーの動作を推測してはいけません。

これらの不変条件を維持してください

• ユーザーが明示的に変更を許可しない限り、呼び出し元から見える動作を維持してください。
• フィルター、コンテンツフィールド、合成された回答、画像、安全制御、スコアに基づく判断を、黙って削除しないでください。
• API キーやシークレットの値を出力しないでください。キーが存在するかどうかだけを確認してください。
• search_queries を作り出すことだけを目的に、隠れた LLM 呼び出しを追加しないでください。
• API の長さ制限内に収まるというだけで、任意のユーザープロンプトをキーワードクエリとして扱わないでください。
• ウェブ調査の意図、必須フィルター、ハンドラーポリシー、回答合成の指示は、それぞれ別の契約として維持してください。
• 省略されたプロバイダーパラメーターも動作に影響するものとして扱ってください。Parallel の設定を省略する前に、デフォルト値を確認してください。
• 互換性シムの背後で、レガシーのプロバイダー SDK 全体を再現しないでください。アプリケーションが実際に使用する契約だけを正規化してください。
• ユーザーが明示的に依頼しない限り、外部シークレットマネージャーやプロバイダーダッシュボードから認証情報を削除しないでください。古くなったコード参照を削除し、チェックイン済みのテンプレートを更新してください。
• モードのマッピングは出発点として扱ってください。アプリケーションの実際のクエリで、レイテンシー、品質、出力の動作を検証してください。
• 必須の動作に、対応する Parallel の同等機能もスコープ内の代替手段もない場合は、破壊的な編集を行う前に作業を中止してください。正確な不足点と、必要最小限の判断事項を報告してください。
• Perplexity の境界で埋め込みが必要となる場合は、そこで作業を中止してください。埋め込みは Parallel Search の代替ではありません。finance_search は、利用側で必要とされる契約に応じて、Search、Chat、または Task を使い、Parallel の汎用インデックス経由で処理してください。ハードな市場データの網羅性、鮮度、または生の結果に関する要件が維持できない場合に限り、作業を中止してください。ユーザーが移行スコープを明示的に拡大しない限り、Agent API のモデルルーティング、サンドボックス、MCP、既存のカスタム関数機能は個別に維持してください。
• Firecrawl の境界で、完全なクロールや URL マッピング、ローカル／プライベートファイルの解析、ブラウザー操作やセッション、スクリーンショットなどのリッチなスクレイプ形式、変更追跡、または承認済みの代替手段がない Firecrawl 固有のプライバシー／セキュリティ制御が必要となる場合は、そこで作業を中止してください。Search と Extract では、これらの契約を再現できません。
• AGENTS.md、CLAUDE.md、CONTRIBUTING.md など、リポジトリ内の指示に従ってください。無関係な作業内容を維持し、ユーザーの変更を決してリセットまたは破棄しないでください。
• インベントリや計画を提示しただけで止めず、安全なリポジトリ内の移行作業を完了してください。ユーザーから依頼されない限り、コミットやプッシュ、ホストされているシークレットの変更、プロバイダーアカウントの変更は行わないでください。

1. 実際の移行範囲を洗い出す

編集前に、現在のブランチと作業ツリーの状態を記録します。対象リポジトリから、同梱のスキャナーを実行します。

python3 <skill-root>/scripts/scan_provider_usage.py .

機械可読な出力には --format json を使用します。スキャナーは依存関係／生成物のディレクトリ、バイナリ、読み取り不可のファイル、サイズの大きすぎるファイルを意図的にスキップします。また、フィールド名だけではプロバイダーに依存しない利用箇所を特定できません。これは洗い出しの補助として扱い、網羅性の証明とは見なさないでください。結果を確認してから、各プロバイダーのレスポンスを利用箇所までたどります。さらに、次の項目も確認します。

• パッケージマニフェストとロックファイル
• REST エンドポイントへの直接アクセスと認証ヘッダー
• SDK クライアント、非同期クライアント、ラッパー、モデルツール定義
• 環境変数スキーマ、使用例、デプロイ設定、ドキュメント
• リクエストビルダー、リトライ、タイムアウト、キャッシュ、可観測性、エラー処理
• レンダリング、ランキング、しきい値、引用、モデルコンテキストに使用されるレスポンスフィールド
• Firecrawl のクロール、バッチ、抽出、ブラウザー、インタラクション、Webhook、ジョブライフサイクルに関する利用箇所
• テスト、モック、フィクスチャ、スナップショット

可能であれば、編集前に既存の対象テストを実行します。現在どの動作がカバーされているか、どの失敗が既存のものか、どの動作を手動で検証する必要があるかを記録します。

編集前に、プロバイダー呼び出し箇所ごとに判断行を記入します。

呼び出し箇所	プロバイダー製品	利用している動作	Parallel の代替経路	意味上の差異	対応
path:line	Search、Scrape、Agent など	呼び出し元が依存する入力、出力、ライフサイクル、ポリシー	該当する場合は正確な製品経路	その経路では維持できない点	migrate、retain、または block

呼び出しを変更する前に、対応を必ず1つ選びます。

• migrate：提案する経路で利用中の契約が維持される場合、または差異の内容についてユーザーの承認がすでに得られている場合に限ります。
• retain：呼び出しが移行範囲外の場合、または未対応の機能を維持するための最小限の安全な手段である場合に選びます。
• block：ユーザーの判断なしでは、指定された範囲の作業を完了できない場合に選びます。必要となる最小限の判断を明記し、独立した migrate の項目は続行します。

プロバイダーのインポートをなくすことだけを目的に、より広範な Parallel 製品を使用してはいけません。もっともらしい結果形式であっても、ソース範囲、費用制御、モデルの動作、ライフサイクル、プライバシーポリシーが同等に維持される証拠にはなりません。

2. 移行範囲を選ぶ

編集前に、次の両方の設計を検討します。

• 直接置換： プロバイダー呼び出しが少数で近接しており、プロバイダー固有のレスポンス型が外部に漏れない場合に使用します。各呼び出しとその利用箇所をまとめて置き換えます。
• アプリケーション所有のウェブデータモジュール： 呼び出しが散在している場合、Parallel の複数製品が必要な場合、またはプロバイダーフィールドがアプリケーション内に漏れている場合に使用します。リクエストの構築、レスポンスの正規化、リトライ、テレメトリーを、呼び出し側向けの小さなインターフェースの内側にまとめます。プロバイダーの詳細を隠す、深いモジュールにしてください。単に呼び出しを通すだけのラッパーは追加しないでください。

今後の検索プロバイダーの変更を局所化し、無関係な呼び出し元の編集を最小限に抑えられる設計を優先します。アプリケーションが旧プロバイダーの生レスポンスを公開している場合は、正規化処理によって文書化されたアプリケーション契約だけを維持するか、すべての利用箇所をまとめて更新します。

3. リクエストを意図的に移行する

Parallel Search API のすべてのリクエストは、次の事実に基づいて構成してください。

• search_queries は必須です。空でないキーワードクエリを少なくとも 1 つ指定してください。呼び出し元のフローで指定できる場合は、内容の異なるキーワードクエリを 2 つまたは 3 つ使用してください。
• objective は任意ですが、指定することを推奨します。自己完結したウェブ調査の目的をここに記載し、ユーザーとの会話全体や回答形式の指示は記載しないでください。
• 直接 REST を呼び出す場合は、https://api.parallel.ai/v1/search、x-api-key、PARALLEL_API_KEY を使用してください。
• 検出されたフレームワークに、必要な契約を維持する最新の Parallel ファーストパーティ統合がない限り、Python と TypeScript の両方で公式の parallel-web パッケージを使用してください。

変換する前に、古い入力をすべて分類してください。

• ウェブ調査全体の目的、コンテキスト、または柔軟な情報源・鮮度の希望 → objective；
• 簡潔な検索プローブ → search_queries；
• 必須または禁止の情報源制限 → advanced_settings.source_policy；
• 回答形式、統合の指示、構造化出力、またはストリーミング → 既存の統合レイヤー、Chat API、または Task API；
• レイテンシ、結果数、キャッシュ、抜粋の制御 → 明示的に選択し、テストしたアプリケーション側のポリシー。

静的な呼び出しでは、目的を明示し、キーワードプローブを 2 つまたは 3 つ指定してください。モデルツールでは、references/integration-patterns.md にある正確に 3 つのクエリを指定するスキーマを使用してください。クエリを 1 つだけ指定する直接呼び出しのフォールバックは、すでにキーワード形式になっている古い値に限り、評価も必要です。意図を黙って切り詰めたり、キーワードのバリエーションを作り出したり、隠れたプランナーを追加したり、厳格なフィルターを文章に移したりしないでください。

分類が終わってから、プロバイダーのマッピングを適用してください。実際の製品要件を満たす設定だけを維持してください。不要な advanced_settings は品質を低下させる場合があります。

送信前に、実行時の値が Parallel V1 の契約に適合しているか検証してください。特に、クエリの数と長さ、目的の長さ、合計 200 ドメインの上限、日付の正規化、対応する地域コードを確認してください。以前のプロバイダーの数値範囲を暗黙のうちに引き継がないでください。

4. レスポンスの動作を移行する

すべての利用箇所を Parallel のレスポンス形式に更新してください。Search API は、url、省略可能な title、省略可能な publish_date、および excerpts 配列を含む、ランキング順の results を返します。以前のプロバイダーが返していた関連度スコア、生成された回答、画像フィールド、応答時間、ページ全体の本文は返しません。

フィールド名だけでなく、フィールドの意味も維持してください。日付のみの publish_date では以前のタイムスタンプの時刻精度は復元されません。search_id はセッション識別子ではなく、SKU の使用数はプロバイダーのクレジットや金額ベースのコストではありません。アプリケーションの契約で変換が定義されている場合に限り正規化し、それ以外の場合は契約の変更を明示してください。

検索以外の動作は、明示的に振り分けてください。

• LLM のコンテキストや簡潔な根拠には、Search API の抜粋を直接使用します。
• 既知の結果 URL からコンテンツ全体を取得するには Extract API を使用し、Search API の session_id を再利用します。
• 根拠に基づく回答には Chat API またはアプリケーションで既存のモデルを使用します。
• 非同期の複数ステップのリサーチや構造化された統合には Task API を使用します。
• 同期的な人物または企業の検索には Entity Search を使用します。

Firecrawl の場合は、ルートを選ぶ前に製品を分類してください。Search は通常 Search に対応します。公開 URL の Markdown またはコンテンツ全体の取得には Extract が対応する場合があります。構造化された複数ページのリサーチには、Task が必要なソース範囲、支出ポリシー、品質の選択、ライフサイクルを維持できる場合に限り Task が対応します。既知 URL からの正確な構造化抽出には、Extract とアプリケーション管理のモデル／パーサーの組み合わせが適しています。Research Index、Crawl、Map、Parse のアップロード、Browser、Interact、Monitor、スクリーンショット、その他の高度なスクレイピング動作は、Search のフィールドマッピングではありません。references/firecrawl.md に従い、明示的な置き換えが承認されるまで、個別の機能を維持してください。

もっともらしい定数で欠落フィールドを補完しないでください。古くなった利用箇所を削除するか、アプリケーションの契約を再設計するか、適切な Parallel API を使用してください。

5. 依存関係と設定を置き換える

• 選択したルートに必要な SDK のみを追加します。Search、Extract、Task には parallel-web、Chat には（アプリケーションに互換性のあるクライアントがすでにある場合を除き）openai を使用します。直接 REST を使う既存の方法のほうがシンプルな場合は、SDK を追加しません。
• retain の行がレガシープロバイダーのパッケージに依存しなくなった場合に限り、そのパッケージを削除し、リポジトリのパッケージマネージャーでロックファイルを再生成します。
• プロバイダーのインポート、クライアントの初期化、エンドポイント、ヘッダーを置き換えるのは、migrate の行に限ります。保持する呼び出しに明示的な境界が設けられるまでは、共有のプロバイダー設定を維持してください。
• チェックイン対象の環境テンプレート、検証スキーマ、セットアップスクリプト、デプロイマニフェスト、サンプル、ドキュメントに PARALLEL_API_KEY を追加します。保持する実行時機能でレガシーキーが不要になった場合に限り、それらの箇所から削除してください。
• Parallel SDK がサポートする範囲で、既存のタイムアウト、再試行、キャンセル、ログ記録の動作を維持してください。サポートされない場合は、アプリケーションの境界でその動作を実装し、テストしてください。
• プロバイダー名が運用担当者の対応に役立つ場合を除き、エラーメッセージではプロバイダー名を使わないでください。

実際のシークレット値をログ、レポート、パッチ、フィクスチャに決して公開したり、書き換えたりしないでください。

6. 構文だけでなく、動作を検証する

次の項目について、テストを追加または更新します。

• search_queries、モード、フィルター、日付、場所を含むリクエストの構築；
• apex ドメイン、サブドメイン、スキーム、パス、ワイルドカード、競合するリスト、プロバイダー固有の上限に対するソースポリシーの正規化；
• クエリ設計の動作：静的リクエスト、クエリを直接1件指定する互換性パス、モデルツールのスキーマ；
• 省略されたレガシーのデフォルト値、2種類のドメインリスト、承認済みの意味的な変更；
• 動的クエリおよびドメインリストの上限値の検証；
• レスポンスの解析と抜粋の結合；
• 結果が空の場合、任意のタイトルや日付がない場合、警告、エラー；
• アプリケーションが所有する契約を維持する正規化処理；
• 使用する場合は、全文取得、合成、エンティティの各ルート；
• スコアのしきい値やプロバイダー固有のフィールドの削除。

リポジトリのテスト実行契約を維持します。対象を絞ったテストで以前プロバイダーパッケージをスタブ化し、その SDK をインストールせずに実行していた場合は、置き換え後の SDK をスタブ化するか、インポートも注入境界の内側に保ちます。同等のクリーンな環境で移行前とまったく同じテストコマンドを再実行します。環境に元からインストールされていたパッケージに依存する成功は、リポジトリが自己完結している証拠にはなりません。

次の順序で実行します。

1. 対象を絞った移行テスト；
2. 必要に応じて、リポジトリのフォーマッター、型チェッカー、リンター、ビルド、より広範なテスト；
3. プロバイダーを完全に削除する場合は、python3 <skill-root>/scripts/scan_provider_usage.py . --provider <legacy-provider> --fail-on-legacy；
4. Perplexity または Firecrawl の検索以外の用途が承認済みで残る場合は、--fail-on-legacy を付けずにプロバイダースキャンを実行し、すべての検出箇所を分類します。その後、移行対象のルートだけをスキャンするか、保持するモジュールが独立している場合に限り、限定的な --exclude パスを使用します。検索と検索以外の用途が混在する境界は、決して除外しないでください；
5. exa、tavily、perplexity、sonar-、firecrawl、sonar への model の完全一致代入、ルーティングされた perplexity/sonar モデル ID、パッケージ名、エンドポイント、キー名を大文字小文字を区別せずに個別に検索します。スキルが対象リポジトリ内にインストールされている場合は、<skill-root> を除外します；
6. 意図しない動作変更、値の漏えい、無関係な編集、古くなったロックファイルがないか、最終差分を確認します；
7. プロバイダーへの呼び出しがこのタスクで明示的に許可され、かつ PARALLEL_API_KEY がすでに利用可能な場合に限り、ライブスモークテストを実行します。キーの値は出力しないでください。

環境に認証情報が存在するだけでは、有料のネットワーク呼び出しは許可されません。許可されている場合は、機密性のない小規模な合成クエリを使用し、warnings、結果の順序、抜粋、エラー時の動作を確認します。代表的な本番クエリを比較するのは、両方のプロバイダーへの送信についてユーザーの承認がある場合、または既存のリポジトリのテストポリシーですでにその比較が明示的に許可されている場合に限ります。ユーザーにシークレットの貼り付けを求めないでください。

完了ゲート

以下の該当するすべての項目が満たされた場合にのみ完了とします。

• 移行対象の範囲内に、旧プロバイダーへの実行時依存関係、インポート、エンドポイント、認証ヘッダー、キー参照、ツール定義、フィクスチャ、古いセットアップ手順が残っていません。
• 移行対象の範囲外にある Perplexity のモデルルーティング、埋め込み、サンドボックス、MCP、カスタム関数の各機能は維持されているか、明示的な阻害要因として記載されています。
• 移行された finance_search のパスでは、評価済みの Parallel ルートと、必要に応じてアプリケーション所有のノーマライザーを通じて、利用側が期待する最終回答または finance_results の契約が維持されています。解決していない厳格な網羅性要件や鮮度要件は、明示的な阻害要因として記載されています。
• 移行対象の範囲外にある Firecrawl のクロール、マップ、ファイル解析、ブラウザー、インタラクション、リッチ形式、変更追跡、セキュリティ／プライバシー、MCP、非同期ジョブの各機能は維持されているか、明示的な阻害要因として記載されています。
• インベントリに記録されたすべての呼び出しに migrate、retain、または block の判定が記録されており、未解決のギャップを解決済みであるかのように編集した block 行はありません。
• Firecrawl の厳密な URL 制約、実行ごとのクレジット上限、spark-1-* モデルの選択、同期／非同期の動作は維持されるか、明示的な承認を得てのみ変更されています。ドメイン許可リスト、予算の省略、推測による Task プロセッサーは、このゲートを満たしません。
• 使用されるすべてのリクエスト機能とレスポンスフィールドに、実装済みの Parallel パスがあるか、動作変更について明示的な承認があります。
• クエリの構築では、調査の目的が維持され、キーワード形式の検索プローブが使われ、該当する直接呼び出しまたはモデルツールの契約に従っています。
• ソースポリシーの移行では、意図された URL の範囲が維持されています。未対応のパス指定またはワイルドカードの動作は明示的に実装されるか、承認済みのギャップとして記録されています。
• テストと静的チェックが合格しているか、既存の無関係な失敗が証拠とともに特定されています。
• プロバイダーが完全に削除された場合は、プロバイダー固有のレガシースキャンに合格しています。そうでない場合、残るすべての検出結果は、承認済みの分離された非検索範囲に属しており、特定された各レスポンスの下流の利用先が追跡されています。
• ライブ呼び出しが明示的に承認され、認証情報が利用可能な場合は、ライブ呼び出しに合格しています。それ以外の場合は、ライブ検証ができていないことを明確に記載しています。
• 最終報告書に、移行した範囲、重要な意味上の選択、検証コマンド、運用担当者に残された外部シークレットのクリーンアップが記載されています。