/pufferlib

name: pufferlib
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.
license: MIT
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.
allowed-tools: Read Bash Grep Python
metadata:
  version: "1.2"
  skill-author: "K-Dense Inc."
  last-reviewed: "2026-07-23"

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

1. Start with bundled synthetic, CPU-only, network-free tools. 2. Do not import an arbitrary environment by dotted path. Bundled tools accept only allowlisted built-ins and slug identifiers. 3. Do not install or execute an unreviewed environment package, native extension, ROM, map, checkpoint, or pickle file. 4. Verify official source, immutable revision, licenses, checksums or attestations, and build hooks. Sandbox native builds and first execution. 5. Cap steps, environments, agents, workers, threads, buffers, memory, disk, render size, and wall time. 6. Keep training and evaluation environments/seeds separate. 7. Default logging to local/none. External logging requires explicit opt-in, disclosure acknowledgment, and separate artifact-upload approval. 8. Never pass W&B or Neptune credentials via CLI, INI, JSON, tags, run names, or logger configuration. Never print them. 9. Never dump all environment variables or recursively search for `.env`. 10. 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