pufferlib
Version-aware guidance for PufferLib reinforcement-learning environments, vectorization, policies, PuffeRL training, evaluation, and safe checkpoint review. Use when adapting Gymnasium/PettingZoo environments to published PufferLib 3.0.0 or working with the redesigned native 4.0 source line.
- License 许可
- MIT
- 最近更新
- 2026-10-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- pufferlib
- license
- MIT
- metadata
- { "version": "1.1", "skill-author": "K-Dense Inc.", "last-reviewed": "2026-07-23" }
- description
- Version-aware guidance for PufferLib reinforcement-learning environments, vectorization, policies, PuffeRL training, evaluation, and safe checkpoint review. Use when adapting Gymnasium/PettingZoo environments to published PufferLib 3.0.0 or working with the redesigned native 4.0 source line.
- allowed-tools
- Read Bash Grep Python
- compatibility
- Bundled CLIs require Python 3.10+ and use only the standard library. Published pufferlib 3.0.0 supports Python >=3.9 but ships as a native-code source archive; current 4.0 source requires Python >=3.10, Torch >=2.9, and an audited CPU/CUDA toolchain. Network, GPU, native builds, environment plug-ins, assets, checkpoints, and external logging are never required by the bundled CLIs.
02 资源文件 14
- 参考文档references/environments.md9.1 KB
- 参考文档references/integration.md8.7 KB
- 参考文档references/policies.md6.8 KB
- 参考文档references/training.md10.2 KB
- 参考文档references/vectorization.md8.2 KB
- 脚本scripts/__init__.py62 B
- 脚本scripts/_common.py6.5 KB
- 脚本scripts/benchmark_vectorization.py8.1 KB
- 脚本scripts/env_contract_validator.py6.7 KB
- 脚本scripts/env_template.py7.1 KB
- 脚本scripts/inspect_checkpoint.py6.7 KB
- 脚本scripts/repro_plan.py5.9 KB
- 脚本scripts/train_template.py9.7 KB
- 脚本scripts/validate_plan.py18.0 KB
03 SKILL.md 正文
PufferLib
Use PufferLib with an explicit version profile. Upstream currently has two incompatible surfaces:
| Profile | Status on 2026-07-23 | Main use |
|---|---|---|
pufferlib==3.0.0 |
Latest stable PyPI release, published 2025-06-23 | Python/Gymnasium/PettingZoo emulation, pufferlib.vector, Torch PuffeRL |
source 4.0 |
Upstream default branch; not the latest stable PyPI artifact | Native C Ocean environments, native CUDA trainer, optional Torch fallback |
Do not combine 3.0 imports with 4.0 config/CLI examples. The 4.0 redesign
removed the 3.0 emulation, vector, and pytorch modules from the current
package tree.
Safe defaults
- Start with bundled synthetic, CPU-only, network-free tools.
- Do not import an arbitrary environment by dotted path. Bundled tools accept only allowlisted built-ins and slug identifiers.
- Do not install or execute an unreviewed environment package, native extension, ROM, map, checkpoint, or pickle file.
- Verify official source, immutable revision, licenses, checksums or attestations, and build hooks. Sandbox native builds and first execution.
- Cap steps, environments, agents, workers, threads, buffers, memory, disk, render size, and wall time.
- Keep training and evaluation environments/seeds separate.
- Default logging to local/none. External logging requires explicit opt-in, disclosure acknowledgment, and separate artifact-upload approval.
- Never pass W&B or Neptune credentials via CLI, INI, JSON, tags, run names, or logger configuration. Never print them.
- Never dump all environment variables or recursively search for
.env. - Hash checkpoint bytes before trusted, sandboxed loading; metadata inspection is not proof of safety.
First local checks
All bundled CLIs are dependency-free and emit strict 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
Defaults are synthetic, deterministic, bounded, local, CPU-only, no-network, and dry-run where training would otherwise occur.
Installation and provenance
Published 3.0.0
PyPI supplies only pufferlib-3.0.0.tar.gz:
sha256: 7df3a3e3f5f894d78d2a1f5374097890aec01473183e748abefe4f3faa10eaa9
Requires-Python: >=3.9
After source/build review, create a pinned uv project:
uv venv --python 3.11
uv add --exact --no-sync "pufferlib==3.0.0"
uv lock
uv sync --frozen
Commit pyproject.toml and uv.lock; verify the archive digest and every
resolved dependency. The source build can compile native code and fetch build
assets, so resolve/build in a sandbox without credentials or sensitive mounts.
The uploaded metadata does not pin Torch or CUDA; do not claim a supported CUDA
matrix that PyPI does not declare.
Current 4.0 source
The reviewed branch head on 2026-07-23 was:
25647630e1b15330bb3153a5a0d3ff8d234c3acf
Pin the commit, not branch 4.0:
uv add --no-sync \
"pufferlib @ git+https://github.com/PufferAI/PufferLib.git@25647630e1b15330bb3153a5a0d3ff8d234c3acf"
uv lock
The current package declares Python >=3.10 and Torch >=2.9. Upstream
PufferTank currently uses Ubuntu 24.04, Python 3.12, and an NVIDIA CUDA
13.0.2/cuDNN development image with the cu130 Torch index, but does not pin
the exact Torch wheel or all system packages. Treat it as a reference, not a
complete lock. Never execute a remote installer directly from a pipe.
Read references/training.md before any installation or build.
Environment workflow
1. Validate the contract
Gymnasium reset returns (observation, info). Step returns:
(observation, reward, terminated, truncated, info)
Validate spaces, shapes, dtypes, finite rewards, booleans, reset-before-step,
reset-after-end, seeding, and cleanup. terminated is an MDP terminal;
truncated is an external cutoff such as a time limit. Preserve the distinction
for bootstrapping and metrics.
python3 scripts/env_contract_validator.py \
--steps 64 --episodes 8 --seed 42
2. Adapt only after review
Published 3.0 uses explicit wrappers:
import pufferlib.emulation
wrapped = pufferlib.emulation.GymnasiumPufferEnv(reviewed_gymnasium_instance)
For a reviewed PettingZoo Parallel environment:
wrapped = pufferlib.emulation.PettingZooPufferEnv(reviewed_parallel_instance)
There is no supported 3.0 pufferlib.emulate(...) shortcut matching the old
skill. Read references/environments.md and references/integration.md.
3. Native environments
Published 3.0 PufferEnv requires
single_observation_space, single_action_space, and num_agents before
super().__init__(buf). It uses in-place vector buffers and returns separate
terminal/truncation arrays plus a list of info dictionaries.
Current 4.0 uses C bindings. Start from upstream ocean/squared (single-agent)
or ocean/target (multi-agent), build one environment in local/sanitized mode,
and verify every buffer size/type/index before optimization.
Vectorization workflow
Published 3.0:
import pufferlib.vector
vecenv = pufferlib.vector.make(
reviewed_creator,
backend=pufferlib.vector.Serial,
num_envs=4,
seed=42,
)
Move to Multiprocessing only after serial traces pass. Record
num_envs, num_workers, batch_size, zero-copy mode, start method, agent
count, masks, and actual returned shapes. For multi-agent environments, batch
length is based on agent slots, not necessarily num_envs.
Current 4.0 config instead uses:
[vec]
total_agents = 4096
num_buffers = 2
num_threads = 16
Read references/vectorization.md. Benchmark fixed work with warmup and at least
three repeats; report simulation and end-to-end training SPS separately. The
bundled benchmark measures only its synthetic harness.
Policy workflow
Published 3.0 policies are Torch modules sized from
single_observation_space/single_action_space. Stable recurrent composition
uses encode_observations and decode_actions; structured emulation uses
pufferlib.pytorch.nativize_dtype and nativize_tensor.
Current 4.0 Torch fallback composes:
pufferlib.models.Policy(encoder=encoder, decoder=decoder, network=network)
It provides MLP, MinGRU, LSTM, and GRU network choices; --slowly selects this
fallback instead of the native backend. Check output/state shapes, masks,
finite values, gradients, and eager-versus-compiled behavior. See
references/policies.md.
Training and evaluation
Published 3.0 trainer import:
from pufferlib import pufferl
trainer = pufferl.PuffeRL(train_config, vecenv, policy)
Current 4.0 CLI:
puffer train ENV_NAME
puffer eval ENV_NAME --load-model-path EXACT_TRUSTED_PATH
puffer sweep ENV_NAME
Generate a plan instead of launching by default:
python3 scripts/train_template.py \
--profile pypi-3.0.0 \
--environment synthetic \
--device cpu \
--total-timesteps 10000
Validate a custom strict-JSON plan:
python3 scripts/validate_plan.py --root . --config plan.json
The schema rejects secret-bearing keys, unbounded resources, dotted environment
paths, invalid vector divisibility, mixed-version options, and coupled
train/eval seeds. See references/training.md.
Logging
PufferLib 3.0 exposes W&B and Neptune; current 4.0 CLI exposes W&B. Both are optional external services. They may transmit configuration, metrics, source metadata, hardware telemetry, output, and approved artifacts, with privacy, retention, access-control, and cost implications.
- W&B credential: named environment variable
WANDB_API_KEY. - Neptune credential: named environment variable
NEPTUNE_API_TOKEN. - Never put values in arguments/config/logs.
- Sanitize config keys before logging.
- Keep source/model upload off unless explicitly approved.
The planner requires both:
python3 scripts/train_template.py \
--logger wandb \
--enable-external-logging \
--acknowledge-external-disclosure
It reports only the required variable name and never reads its value.
Checkpoint workflow
PufferLib 3.0 and the 4.0 Torch fallback use Torch serialization; current native
4.0 writes opaque .bin weights. PyTorch warns that untrusted models are
programs and that torch.load uses unpickling.
python3 scripts/inspect_checkpoint.py checkpoint.pt \
--root . \
--expected-sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
The inspector hashes and classifies only. It does not call torch.load, import
pickle/Torch, inspect archive members, or extract files. Verify source, license,
architecture, environment revision, sidecar metadata, and checksum before any
sandboxed load. Never use latest in a reproducible evaluation.
Bundled files
Scripts
scripts/env_template.py— deterministic synthetic Gymnasium-style template.scripts/env_contract_validator.py— bounded contract and seed checks.scripts/benchmark_vectorization.py— capped serial/spawn synthetic benchmark.scripts/train_template.py— non-executing 3.0/4.0 training-plan generator.scripts/validate_plan.py— strict config/resource/security validator.scripts/inspect_checkpoint.py— metadata/hash inspection without deserialization.scripts/repro_plan.py— separate-seed evaluation and benchmark plan.
References
references/environments.md— Gymnasium, stable PufferEnv, emulation, native C.references/vectorization.md— backends, shapes, start methods, benchmarks.references/policies.md— stable/current policy contracts and state safety.references/training.md— installs, config, CLI, PuffeRL, eval, logs, checkpoints.references/integration.md— migration matrix, third-party and credential safety.
Dated upstream sources
- PyPI pufferlib 3.0.0 — released 2025-06-23; checked 2026-07-23.
- PyPI 3.0.0 metadata — digest/dependencies; checked 2026-07-23.
- PufferLib official docs — current 4.0 docs; checked 2026-07-23.
- PufferLib source — default branch and implementation; checked 2026-07-23.
- PufferTank 4.0 Dockerfile — CUDA/Python reference; checked 2026-07-23.
- PufferLib 2.0 paper — Reinforcement Learning Journal, 2025; use only for its stated benchmarks.
- PufferLib compatibility paper — submitted 2024-06-18; describes an earlier API/performance profile.
04 同仓库更多 Skills
zarr-python
Chunked N-D arrays for cloud storage (Zarr-Python 3). Compressed arrays, parallel I/O, S3/GCS via fsspec, NumPy/Dask/Xarray compatible, for large-scale scientific computing pipelines.
video-use
Edit any video by conversation. Transcribe, cut, color grade, generate overlay animations, burn subtitles — for talking heads, montages, tutorials, travel, interviews. No presets, no menus. Ask questions, confirm the plan, execute, iterate, persist. Production-correctness rules are hard; everything else is artistic freedom.
venue-templates
Prepare journal manuscripts, conference papers, research posters, and grant documents using venue-specific formatting guidance and bundled LaTeX scaffolds. Use when selecting an official template, checking current page or anonymity rules, adapting academic writing to a venue, or inspecting a submission PDF.
vaex
Use this skill for processing and analyzing large tabular datasets (billions of rows) that exceed available RAM. Vaex excels at out-of-core DataFrame operations, lazy evaluation, fast aggregations, efficient visualization of big data, and machine learning on large datasets. Apply when users need to work with large CSV/HDF5/Arrow/Parquet files, perform fast statistics on massive datasets, create visualizations of big data, or build ML pipelines that do not fit in memory.
usfiscaldata
Query the U.S. Treasury Fiscal Data REST API for federal financial data. No API key required. Use for national debt (Debt to the Penny), Daily Treasury Statements, Monthly Treasury Statements, Treasury securities auctions, interest rates, foreign exchange rates, savings bonds, or U.S. government revenue and spending statistics.
uncertainty-and-units
Track physical units and propagate measurement uncertainty in scientific calculations using pint and uncertainties. Use for unit conversion and dimensional checking, GUM uncertainty budgets, Type A and Type B evaluation, coverage factors and expanded uncertainty, Monte Carlo propagation, significant-figure and plus-minus reporting, error propagation through curve fits, CODATA constants, auditing Python code for stripped units or broken uncertainty propagation, and order-of-magnitude plausibility checks using dimensionless groups (Reynolds, Peclet, Damkohler, Knudsen, Biot, Womersley), characteristic scales such as diffusion time or Debye length, and observed magnitude ranges. Trigger on "is this number physically reasonable", "sanity check these units", "what regime is this flow in", or a result that looks off by orders of magnitude.