pufferlib

PufferLib

明示的なバージョンプロファイルを指定して PufferLib を使用してください。アップストリームには現在、互換性のない 2 つのインターフェースがあります。

プロファイル	2026-07-23 時点のステータス	主な用途
pufferlib==3.0.0	最新の安定版 PyPI リリース、2025-06-23 公開	Python／Gymnasium／PettingZoo のエミュレーション、pufferlib.vector、Torch PuffeRL
source 4.0	アップストリームのデフォルトブランチ。最新の安定版 PyPI アーティファクトではありません	ネイティブ C Ocean 環境、ネイティブ CUDA トレーナー、オプションの Torch フォールバック

3.0 のインポートと 4.0 の設定／CLI の例を組み合わせないでください。4.0 の再設計により、現在のパッケージツリーから 3.0 の emulation、vector、pytorch モジュールが削除されています。

安全なデフォルト設定

1. バンドルされた合成データ、CPU のみ、ネットワーク不使用のツールから始めてください。
2. 任意の環境をドット区切りのパスでインポートしないでください。バンドルされたツールが受け付けるのは、許可リストに登録された組み込みのものとスラッグ識別子のみです。
3. 未レビューの環境パッケージ、ネイティブ拡張、ROM、マップ、チェックポイント、pickle ファイルをインストールまたは実行しないでください。
4. 公式ソース、不変のリビジョン、ライセンス、チェックサムまたはアテステーション、ビルドフックを確認してください。ネイティブビルドと初回実行はサンドボックス内で行ってください。
5. ステップ数、環境数、エージェント数、ワーカー数、スレッド数、バッファー、メモリ、ディスク、レンダリングサイズ、実行時間に上限を設定してください。
6. トレーニング環境と評価環境／シードは分けてください。
7. ログ記録はデフォルトでローカルまたは無効にしてください。外部へのログ記録には、明示的なオプトイン、情報開示への確認、アーティファクトのアップロードに対する個別の承認が必要です。
8. W&B または Neptune の認証情報を CLI、INI、JSON、タグ、実行名、ロガー設定経由で渡さないでください。表示も禁止です。
9. 環境変数をすべてダンプしたり、.env を再帰的に検索したりしないでください。
10. 信頼できるサンドボックス内で読み込む前に、チェックポイントのバイト列をハッシュ化してください。メタデータを調べても、安全性の証明にはなりません。

最初に行うローカルチェック

バンドルされた CLI はすべて依存関係がなく、厳密な JSON を出力します。

python3 scripts/env_template.py --help
python3 scripts/env_contract_validator.py
python3 scripts/benchmark_vectorization.py --backend serial
python3 scripts/train_template.py
python3 scripts/validate_plan.py
python3 scripts/repro_plan.py

デフォルトは合成データ、決定論的、上限付き、ローカル、CPU のみ、ネットワーク不使用で、トレーニングが発生する場合はドライランです。

インストールと来歴

公開されている 3.0.0

PyPI で提供されているのは pufferlib-3.0.0.tar.gz のみです。

sha256: 7df3a3e3f5f894d78d2a1f5374097890aec01473183e748abefe4f3faa10eaa9
Requires-Python: >=3.9

ソース／ビルドをレビューした後、uv プロジェクトを固定してください。

uv venv --python 3.11
uv add --exact --no-sync "pufferlib==3.0.0"
uv lock
uv sync --frozen

pyproject.toml と uv.lock をコミットし、アーカイブのダイジェストと解決されたすべての依存関係を検証してください。ソースからのビルドではネイティブコードがコンパイルされ、ビルドアセットが取得される可能性があるため、認証情報や機密性の高いマウントのないサンドボックス内で依存関係の解決／ビルドを行ってください。アップロードされたメタデータでは Torch や CUDA が固定されていません。PyPI が宣言していない CUDA 対応マトリックスを、サポート対象として示さないでください。

現在の 4.0 ソース

2026-07-23 にレビューしたブランチの HEAD は次のとおりです。

25647630e1b15330bb3153a5a0d3ff8d234c3acf

ブランチ 4.0 ではなく、コミットを固定してください。

uv add --no-sync \
  "pufferlib @ git+https://github.com/PufferAI/PufferLib.git@25647630e1b15330bb3153a5a0d3ff8d234c3acf"
uv lock

現在のパッケージは Python >=3.10 と Torch >=2.9 を宣言しています。アップストリームの PufferTank は現在、Ubuntu 24.04、Python 3.12、cu130 Torch インデックスを使用する NVIDIA CUDA 13.0.2／cuDNN 開発イメージを使用していますが、Torch ホイールの厳密なバージョンやすべてのシステムパッケージは固定していません。完全なロックファイルではなく、参考資料として扱ってください。リモートインストーラーをパイプから直接実行しないでください。

インストールまたはビルドを行う前に、references/training.md を読んでください。

環境のワークフロー

1. 契約を検証する

Gymnasium の reset は (observation, info) を返します。step は次の値を返します。

(observation, reward, terminated, truncated, info)

スペース、形状、データ型、有限の報酬、ブール値、step の前の reset、終了後の reset、シード設定、クリーンアップを検証してください。terminated は MDP の終了であり、truncated は時間制限などの外部要因による打ち切りです。ブートストラップとメトリクスでは、この区別を保持してください。

python3 scripts/env_contract_validator.py \
  --steps 64 --episodes 8 --seed 42

2. レビュー後にのみアダプターを適用する

公開されている 3.0 では、明示的なラッパーを使用します。

import pufferlib.emulation

wrapped = pufferlib.emulation.GymnasiumPufferEnv(reviewed_gymnasium_instance)

レビュー済みの PettingZoo Parallel 環境の場合：

wrapped = pufferlib.emulation.PettingZooPufferEnv(reviewed_parallel_instance)

以前のスキルに相当する、サポート対象の 3.0 pufferlib.emulate(...) ショートカットはありません。references/environments.md と references/integration.md を読んでください。

3. ネイティブ環境

公開版 3.0 の PufferEnv では、super().__init__(buf) の前に single_observation_space、single_action_space、num_agents が必要です。 インプレースのベクターバッファーを使用し、終了・打ち切りの配列と、情報辞書のリストを個別に返します。

現在の 4.0 では C バインディングを使用します。上流の ocean/squared（単一エージェント） または ocean/target（マルチエージェント）をベースにし、ローカル／サニタイズモードで 環境を 1 つ構築してから、最適化の前に各バッファーのサイズ、型、インデックスを確認してください。

ベクトル化のワークフロー

公開版 3.0：

import pufferlib.vector

vecenv = pufferlib.vector.make(
    reviewed_creator,
    backend=pufferlib.vector.Serial,
    num_envs=4,
    seed=42,
)

シリアル実行のトレースが合格してから、Multiprocessing に移行してください。num_envs、num_workers、batch_size、ゼロコピーのモード、開始方法、エージェント数、マスク、実際に返される形状を記録してください。マルチエージェント環境では、バッチ長は num_envs ではなく、エージェントのスロット数に基づく場合があります。

現在の 4.0 では、代わりに次の設定を使用します：

[vec]
total_agents = 4096
num_buffers = 2
num_threads = 16

references/vectorization.md を読んでください。ウォームアップを行い、少なくとも 3 回繰り返して、固定された処理量をベンチマークしてください。シミュレーションの SPS とエンドツーエンドのトレーニングの SPS は分けて報告してください。同梱のベンチマークが測定するのは、合成テストハーネスのみです。

ポリシーのワークフロー

公開版 3.0 のポリシーは、single_observation_space／single_action_space に基づくサイズの Torch モジュールです。安定した再帰的合成には encode_observations と decode_actions を使用し、構造化データのエミュレーションには pufferlib.pytorch.nativize_dtype と nativize_tensor を使用します。

現在の 4.0 の Torch フォールバックでは、次のものを合成します：

pufferlib.models.Policy(encoder=encoder, decoder=decoder, network=network)

MLP、MinGRU、LSTM、GRU のネットワークを選択できます。--slowly を指定すると、ネイティブバックエンドの代わりにこのフォールバックが選択されます。出力と状態の形状、マスク、有限値、勾配、Eager とコンパイル済みの動作を確認してください。references/policies.md を参照してください。

トレーニングと評価

公開版 3.0 のトレーナーのインポート：

from pufferlib import pufferl

trainer = pufferl.PuffeRL(train_config, vecenv, policy)

現在の 4.0 の CLI：

puffer train ENV_NAME
puffer eval ENV_NAME --load-model-path EXACT_TRUSTED_PATH
puffer sweep ENV_NAME

デフォルトでは起動せず、代わりにプランを生成します：

python3 scripts/train_template.py \
  --profile pypi-3.0.0 \
  --environment synthetic \
  --device cpu \
  --total-timesteps 10000

カスタムの strict-JSON プランを検証します：

python3 scripts/validate_plan.py --root . --config plan.json

スキーマでは、シークレットを含むキー、上限のないリソース、ドット区切りの環境パス、無効なベクトルの可分性、異なるバージョンのオプションの混在、連動するトレーニング／評価シードが拒否されます。references/training.md を参照してください。

ロギング

PufferLib 3.0 では W&B と Neptune を利用でき、現在の 4.0 CLI では W&B を利用できます。どちらも任意の外部サービスです。設定、メトリクス、ソースメタデータ、ハードウェアのテレメトリ、出力、承認済みアーティファクトが送信される場合があり、プライバシー、保持期間、アクセス制御、コストに影響します。

• W&B の認証情報：名前付き環境変数 WANDB_API_KEY。
• Neptune の認証情報：名前付き環境変数 NEPTUNE_API_TOKEN。
• 値を引数／設定／ログに記載しないでください。
• ログに記録する前に、設定キーをサニタイズしてください。
• 明示的に承認されない限り、ソース／モデルのアップロードを無効にしてください。

プランナーでは、次の両方が必須です：

python3 scripts/train_template.py \
  --logger wandb \
  --enable-external-logging \
  --acknowledge-external-disclosure

必要な変数名のみを報告し、その値は読み取りません。

チェックポイントのワークフロー

PufferLib 3.0 と 4.0 の Torch フォールバックでは Torch シリアライズを使用します。現在のネイティブ 4.0 では、不透明な .bin 重みが書き込まれます。PyTorch は、信頼できないモデルはプログラムであり、torch.load はアンピックリングを使用すると警告しています。

python3 scripts/inspect_checkpoint.py checkpoint.pt \
  --root . \
  --expected-sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

インスペクターが行うのはハッシュの計算と分類のみです。torch.load の呼び出し、pickle／Torch のインポート、アーカイブメンバーの検査、ファイルの展開は行いません。サンドボックス内でロードする前に、ソース、ライセンス、アーキテクチャ、環境のリビジョン、サイドカーメタデータ、チェックサムを確認してください。再現可能な評価では latest を決して使用しないでください。

同梱ファイル

スクリプト

• scripts/env_template.py — 決定論的な合成 Gymnasium 形式のテンプレート。
• scripts/env_contract_validator.py — 上限付きのコントラクトとシードのチェック。
• scripts/benchmark_vectorization.py — 上限付きのシリアル／spawn 合成ベンチマーク。
• scripts/train_template.py — 実行を伴わない 3.0／4.0 トレーニングプラン生成ツール。
• scripts/validate_plan.py — 厳密な設定／リソース／セキュリティの検証ツール。
• scripts/inspect_checkpoint.py — デシリアライズを行わないメタデータ／ハッシュの検査ツール。
• scripts/repro_plan.py — シードを分離した評価とベンチマークのプラン。

参考資料

• references/environments.md — Gymnasium、stable PufferEnv、エミュレーション、ネイティブ C。
• references/vectorization.md — バックエンド、形状、開始方法、ベンチマーク。
• references/policies.md — stable/current のポリシー契約と状態の安全性。
• references/training.md — インストール、設定、CLI、PuffeRL、評価、ログ、チェックポイント。
• references/integration.md — 移行マトリックス、サードパーティ製ソフトウェアと認証情報の安全性。

日付付きの上流ソース

• PyPI pufferlib 3.0.0 — 2025-06-23 にリリース、2026-07-23 に確認。
• PyPI 3.0.0 メタデータ — ダイジェスト／依存関係、2026-07-23 に確認。
• PufferLib 公式ドキュメント — 現行の 4.0 ドキュメント、 2026-07-23 に確認。
• PufferLib ソース — デフォルトブランチと 実装、2026-07-23 に確認。
• PufferTank 4.0 Dockerfile — CUDA／Python のリファレンス、2026-07-23 に確認。
• PufferLib 2.0 論文 — Reinforcement Learning Journal、2025 年。記載されているベンチマークに限って使用してください。
• PufferLib 互換性論文 — 2024-06-18 に投稿。以前の API／パフォーマンスプロファイルについて説明しています。

関連スキル

• stable-baselines3：本番環境向けの強化学習アルゴリズム（PPO、SAC、DQN、TD3、DDPG、A2C）を、scikit-learn のような API で提供します。
• evaluating-cosmos-policy：LIBERO および RoboCasa のシミュレーション環境で NVIDIA Cosmos Policy を評価します。
• fine-tuning-serving-openpi：JAX または PyTorch バックエンドを使用して Physical Intelligence OpenPI モデル（pi0、pi0-fast、pi0.5）をファインチューニングし、ロボットポリシー推論向けに提供しま