earth2studio-create-datasource

データソースの作成と検証

目的

新しい Earth2Studio データソースラッパーを実装するためのエンドツーエンドのワークフローです。リモートデータストア（S3、GCS、Azure、HTTP、HuggingFace）を Earth2Studio の非同期データ取得インフラストラクチャに接続します。分析から、実装、テスト、検証、PR の提出までを扱います。

前提条件

• uv を使用できる Earth2Studio の開発環境（uv run python が動作すること）
• フォーク（origin）とアップストリーム（upstream）のリモートが設定された Git
• 対象のリモートデータストアへのアクセス権（非公開の場合は認証情報）
• Python 3.10 以降

ワークスペース

pyproject.toml があるディレクトリを使用します。Harbor の評価では、パスを維持して /workspace/output/ に書き込みます。evals/targets/ は読み込まないでください。

手順

Python 環境： 常に uv run python またはローカルの .venv を使用してください。 システムの Python を直接使用しないでください。

すべての手順を順番に実行してください。

[CONFIRM] のゲート： 明示的なユーザー承認が必要なのは、Step 1（ソースタイプ）と Step 12（サニティチェック用プロット）のみです。それ以外の [CONFIRM] マーカーは参考情報です。判断内容をその場で提示し、作業を止めずに進めてください。

成果物を先に作成： 追加の調査、ドキュメント作成、登録、CHANGELOG、PR の作業に進む前に、ソースファイルとテストファイル（Steps 6–7）を作成してください。ユーザーが実装のみを求めている場合は、Steps 8–14 を省略してください。

完了前に： リポジトリのルートで検証コマンドを実行し、結果がセッションログに表示されるようにしてください。

uv run pytest test/data/test_<source>.py -x
make format && make lint

簡潔に： 長いアーキテクチャレポートは避け、判断内容を数文でまとめてからファイルの作成に進んでください。

停止状態またはユーザーからのフィードバック このスキルの使用中にエージェントが行き詰まった場合、またはユーザーから訂正があった場合は、スキルの関連箇所を慎重に確認し、改善してください。簡潔にしてください。

1 回の実行につきソースタイプは 1 つです。 関連するタイプについては、再度実行してください。

参照ファイル

該当する手順で、必要に応じて以下を読み込んでください。

ファイル	内容	読み込むタイミング
references/implementation-guide.py	FILL コメント付きのソースひな形	Steps 3–10
references/testing-guide.py	FILL コメント付きのテストひな形	Step 11
references/validation-guide.md	プロットテンプレート、PR 本文テンプレート、Greptile への対応	Steps 12–14（任意、テンプレート用）

---

ワークフローの概要

Step 0: Obtain reference → Step 1: Determine type → Step 2: Dependencies
→ Step 3: Add deps → Step 4: Create lexicon → Step 5: Update vocab/schema
→ Step 6: Create skeleton → Step 7: Implement source → Step 8: Register
→ Step 9: Documentation → Step 10: CHANGELOG → Step 11: Tests
→ Step 12: Validate & plots (user confirms) → Step 13: PR + sanity comment
→ Step 14: Greptile review

---

Step 0 — リモートデータストアの参照情報を取得する

$ARGUMENTS が指定されている場合は、それを使用してください（URL → WebFetch、ファイルパス → 読み込み）。

指定されていない場合は、次のように質問してください。

リモートデータストアの URL、API ドキュメントへのリンク、または説明を入力してください。ストレージ形式、アクセスパターン、変数一覧、時間・空間解像度を把握するために使用します。

---

Step 1 — ソースタイプを決定する

プロトコル	戻り値	lead_time があるか	用途
DataSource	xr.DataArray	いいえ	格子状の解析／再解析
ForecastSource	xr.DataArray	はい	格子状の予報
DataFrameSource	pd.DataFrame	いいえ	疎な観測／地点観測
ForecastFrameSource	pd.DataFrame	はい	疎な予報観測

主な判断基準：格子状か疎か → DataArray か DataFrame、解析か予報か → Source か ForecastSource。

[CONFIRM — ソースタイプ]

推奨するタイプとその理由を提示し、確認を求めてください。

---

Step 2 — リモートストアを調査し、依存関係を提案する

分析項目： ストレージバックエンド、ファイル形式、認証、アクセスパターン、時間的／空間的解像度、変数の一覧。

fsspec を優先します：

バックエンド	推奨	避けるもの
AWS S3	s3fs（コア依存関係）	boto3 を直接使用
GCS	gcsfs（コア依存関係）	google-cloud-storage
Azure	adlfs	azure-storage-blob
HTTP	fsspec（コア依存関係）	requests
HuggingFace	huggingface_hub（コア依存関係）	カスタムスクリプト

fsspec でストアにアクセスできない場合に限り、専用ライブラリを使用します。

pyproject.toml を確認し、すでに存在するパッケージは提案しないでください。 コア依存関係には、s3fs、gcsfs、fsspec、zarr、netCDF4、h5py、 pygrib、huggingface-hub、pandas、pyarrow が含まれます。

[確認 — 依存関係とアクセスパターン]

提示する項目：バックエンド、fsspec ファイルシステム、新規パッケージ（ライセンスを含む）、認証方法。

---

Step 3 — 依存関係を追加する

ここから Step 10 まで、references/implementation-guide.py を読み込んでください。

新しいパッケージが必要な場合：

1. uv add --extra data <package>
2. uv lock
3. OptionalDependencyFailure パターンを使用して、オプションの依存関係のインポートを追加します。

---

Step 4 — Lexicon クラスを作成する

以下を含む earth2studio/lexicon/<source_name>.py を作成します。

• metaclass=LexiconType
• E2S 名 → リモートキーを対応付ける VOCAB: dict[str, str]
• tuple[str, Callable] を返す get_item(cls, val)
• 構造化キーには :: 区切りを使用します。

リモート変数を E2STUDIO_VOCAB（earth2studio/lexicon/base.py にある 282 個の項目）に対応付けます。

[確認 — Lexicon と変数の対応付け]

提示する項目：クラス名、キー形式、完全な対応表、修飾子、参照 URL。

---

Step 5 — 必要に応じて E2STUDIO_VOCAB / SCHEMA を更新する

• 新しい語彙：surface は説明的な略語、pressure は {name}{level}
• 新しいスキーマフィールド：DataFrame ソースのみ対象とし、E2STUDIO_SCHEMA を確認します。

[確認 — 語彙とスキーマの更新]

更新が不要な場合は省略します。

---

Step 6 — データソースのひな形ファイルを作成する

標準のメソッド順序に従います。

1. クラス定数
2. SCHEMA
3. __init__
4. _async_init
5. __call__
6. fetch
7. _create_tasks
8. fetch_wrapper
9. fetch_array
10. _validate_time
11. ヘルパー
12. cache プロパティ
13. available クラスメソッド

並列実行には非同期タスクのデータクラスパターンを使用します。

[確認 — ひな形]

提示する項目：クラス名、ファイルパス、ひな形コード、タスクのデータクラス。

---

Step 7 — データソースとテストを実装する

テストファイルは同等に重要な成果物です。 ソースと並べて test/data/test_<filename>.py を作成してください。非同期ソースには test_<source>_call_mock を追加します。

同期ソース： prep_data_inputs／prep_forecast_inputs と、直接の __call__ を使用します。

非同期ソース： 必須パターンについては references/implementation-guide.py を参照してください。 _sync_async、managed_session、gather_with_concurrency、async_retry、純粋な非同期 I/O、try/finally によるクリーンアップ。コンストラクターのパラメーター：cache=True、verbose=True、async_timeout=600、async_workers=16、retries=3。DataFrame ソースには time_tolerance を追加します。

---

Step 8 — ソースを登録する

• earth2studio/data/__init__.py — アルファベット順でインポート
• earth2studio/lexicon/__init__.py — アルファベット順でインポート
• pyproject.toml の依存関係を確認します。

---

Step 9 — ドキュメントを更新する

• 適切な RST ファイル（datasources_analysis.rst / _forecast.rst / _dataframe.rst）に追加します。
• クラスの docstring：Parameters、Warning（ダウンロードサイズ）、Note（参照 URL）、Badges（最後）
• すべての公開メソッドに NumPy 形式の docstring を記述します。

---

Step 10 — CHANGELOG.md を更新する

現在の未リリースバージョンの項目として追加します。形式については references/implementation-guide.py の REGISTRATION CHECKLIST を参照してください。

ソースごとに 1 行で記載します。lexicon の項目を別途追加しないでください。

---

ステップ 11 — スタイルを確認し、テストを拡充する

make format && make lint && make license を実行します。テストのひな形を確認するには、references/testing-guide.py を読み込みます。必須テストは test_<source>_fetch（低速）、_cache（低速）、_call_mock、_exceptions、_available です。--slow を付けてカバレッジ 90% 以上を目指します。

[CONFIRM — テスト]

テストファイル、関数、カバレッジを提示します。

---

ステップ 12 — 変数を検証し、サニティチェックを行う

1. すべての辞書変数を実際のデータと照合して検証します（スクリプトを実行し、コミットしないでください）
2. 有効なデータが 10% 未満の変数を削除します
3. サニティチェック用のプロットを作成します（格子状または疎なテンプレート）
4. プロットのパスをユーザーに伝え、目視での確認を求めます

[CONFIRM — サニティチェック用プロット]

ユーザーはプロットを必ず目視で確認する必要があります。確認を得るまで先に進まないでください。

---

ステップ 13 — ブランチを作成し、コミットして、PR を作成する

1. ブランチ feat/data-source-<name> を作成します
2. コミットします（サニティチェック用スクリプト／画像は追加しないでください）
3. フォークにプッシュします
4. gh pr create --repo NVIDIA/earth2studio
5. 直ちにサニティチェックの検証結果を PR コメントとして投稿します。以下を含めてください。
   • 変数のカバレッジ表（名前、件数、範囲、単位）
   • データ検証の概要（地域、嵐／観測所、期間）
   • 主な調査結果（物理的に妥当な値、検証済みの変換）
   • <details> ブロック内に完全な検証スクリプト
   • 画像のプレースホルダー：``

[CONFIRM — 送信準備完了]

PR を作成する前に、すべての手順が完了していることを確認します。

---

ステップ 14 — 自動コードレビュー

1. Greptile のレビューを待機します（タイムアウト 5 分）
2. フィードバックを分類します（バグ／スタイル／パフォーマンス／ドキュメント／提案／誤検出）
3. トリアージ表をユーザーに提示します
4. 承認された修正を実施します
5. PR コメントに返信します
6. プッシュします

[CONFIRM — レビューのトリアージ]

対応するコメントをユーザーが承認します。

---

例

User: Add a data source for the NOAA GFS analysis on S3
Agent: [loads skill, proceeds through Steps 0–14]

---

制限事項

• 1 回の実行につき、ソースタイプは 1 つです
• 検証にはネットワークアクセスが必要です（ステップ 12）
• すべてのファイルに SPDX ライセンスヘッダーが必要です

---

注意事項

推奨： uv run python、loguru.logger、__init__.py／RST／CHANGELOG でのアルファベット順、標準的なメソッドの順序、非同期ユーティリティ（managed_session、gather_with_concurrency、async_retry）、純粋な非同期 I/O、docstring 内の参照 URL、try/finally によるクリーンアップ。

避ける： asyncio.to_thread、単独の tqdm.gather、読み込みに xarray を使うこと、ファイル全体のダウンロード。

絶対にしない： loop.set_default_executor()、シークレットのコミット、サニティチェック用スクリプト／画像のコミット。