# Pufferlib

> Guía consciente de versión para entornos de refuerzo de PufferLib, vectorización, políticas, entrenamiento PuffeRL, evaluación y revisión segura de checkpoints, en PufferLib 3.0.0 o en la línea nativa 4.0.

Fuente: https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/pufferlib
Markdown: https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/pufferlib.md

Repositorio: https://github.com/K-Dense-AI/scientific-agent-skills
Autor: K-Dense-AI
Licencia: MIT
Actualizado: el mes pasado
Coste de contexto: 73 tok instalada, 2.9k tok al activarse, 31.6k tok con todos los archivos del bundle
Bundle: 15 archivos, 123 KB
Permisos que pide: read bash grep python

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add K-Dense-AI/scientific-agent-skills --skill pufferlib --agent claude-code
# Cursor
npx -y skills add K-Dense-AI/scientific-agent-skills --skill pufferlib --agent cursor
# Codex
npx -y skills add K-Dense-AI/scientific-agent-skills --skill pufferlib --agent codex
# Gemini CLI
npx -y skills add K-Dense-AI/scientific-agent-skills --skill pufferlib --agent gemini
# Windsurf
npx -y skills add K-Dense-AI/scientific-agent-skills --skill pufferlib --agent windsurf
# Cline
npx -y skills add K-Dense-AI/scientific-agent-skills --skill pufferlib --agent cline
```

## Qué hace

- Distingue entre el perfil publicado `pufferlib==3.0.0` (Gymnasium/PettingZoo, `pufferlib.vector`, PuffeRL con Torch) y la fuente nativa 4.0, sin mezclar sus APIs.
- Ofrece CLIs locales sin red ni dependencias para validar plantillas de entornos, vectorización, entrenamiento y checkpoints.
- Aplica defaults seguros: solo entornos allowlisted, sin instalar paquetes/checkpoints sin revisar, con límites de pasos, workers, memoria y tiempo.
- Da pautas de procedencia: verificar el hash del paquete PyPI o el commit exacto de la rama 4.0 antes de instalar.

## Cuándo usarla

- Adaptar entornos Gymnasium/PettingZoo a PufferLib 3.0.0 publicado.
- Trabajar con la línea de código fuente nativa 4.0 (entornos Ocean en C, entrenador CUDA nativo).
- Necesitar vectorización, políticas o entrenamiento/evaluación con PuffeRL.
- Revisar de forma segura un checkpoint antes de cargarlo.

## Qué la activa

- "Adapta este entorno de Gymnasium a PufferLib 3.0.0"
- "Valida la plantilla de entorno con los scripts de PufferLib"
- "Compara el backend de vectorización serial de PufferLib"
- "Revisa este checkpoint de PufferLib antes de cargarlo"

## Antes de instalar

- Los CLIs incluidos solo necesitan Python 3.10+ y la librería estándar; PufferLib 3.0.0 requiere Python >=3.9 y la fuente 4.0 requiere Python >=3.10 y Torch >=2.9.
- Necesita en el PATH: python3
- makes network requests

## Archivos

- SKILL.md — 11 KB
- references/environments.md — 9 KB
- references/integration.md — 9 KB
- references/policies.md — 7 KB
- references/training.md — 10 KB
- references/vectorization.md — 8 KB
- scripts/__init__.py — 62 B
- scripts/_common.py — 7 KB
- scripts/benchmark_vectorization.py — 8 KB
- scripts/env_contract_validator.py — 7 KB
- scripts/env_template.py — 7 KB
- scripts/inspect_checkpoint.py — 7 KB
- scripts/repro_plan.py — 6 KB
- scripts/train_template.py — 10 KB
- scripts/validate_plan.py — 18 KB

## SKILL.md

Reproducido tal cual desde K-Dense-AI/scientific-agent-skills bajo MIT. Esta sección es el documento original y está en inglés.

# 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:

```bash
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`:

```text
sha256: 7df3a3e3f5f894d78d2a1f5374097890aec01473183e748abefe4f3faa10eaa9
Requires-Python: >=3.9
```

After source/build review, create a pinned uv project:

```bash
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:

```text
25647630e1b15330bb3153a5a0d3ff8d234c3acf
```

Pin the commit, not branch `4.0`:

```bash
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:

```python
(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.

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

### 2. Adapt only after review

Published 3.0 uses explicit wrappers:

```python
import pufferlib.emulation

wrapped = pufferlib.emulation.GymnasiumPufferEnv(reviewed_gymnasium_instance)
```

For a reviewed PettingZoo Parallel environment:

```python
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:

```python
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:

```ini
[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:

```python
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:

```python
from pufferlib import pufferl

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

Current 4.0 CLI:

```bash
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:

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

Validate a custom strict-JSON plan:

```bash
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:

```bash
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.

```bash
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](https://pypi.org/project/pufferlib/3.0.0/) —
  released 2025-06-23; checked 2026-07-23.
- [PyPI 3.0.0 metadata](https://pypi.org/pypi/pufferlib/3.0.0/json) —
  digest/dependencies; checked 2026-07-23.
- [PufferLib official docs](https://puffer.ai/docs.html) — current 4.0 docs;
  checked 2026-07-23.
- [PufferLib source](https://github.com/PufferAI/PufferLib) — default branch and
  implementation; checked 2026-07-23.
- [PufferTank 4.0 Dockerfile](https://github.com/PufferAI/PufferTank/blob/4.0/puffertank.dockerfile)
  — CUDA/Python reference; checked 2026-07-23.
- [PufferLib 2.0 paper](https://openreview.net/forum?id=qRyteMTgn0) —
  Reinforcement Learning Journal, 2025; use only for its stated benchmarks.
- [PufferLib compatibility paper](https://arxiv.org/abs/2406.12905) —
  submitted 2024-06-18; describes an earlier API/performance profile.

## Dónde encaja

- Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código.
- Creador: [K-Dense-AI](https://skillsagentes.com/creators/k-dense-ai.md) — 163 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Citation Management](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/citation-management.md): Gestión integral de citas académicas: busca en OpenAlex, PubMed y Google Scholar, extrae metadatos precisos, valida citas y genera entradas BibTeX correctamente formateadas.
- [Scientific Slides](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/scientific-slides.md): Crea decks de diapositivas y presentaciones para charlas de investigación: PowerPoint, presentaciones de conferencia, seminarios, defensas de tesis. Da estructura, plantillas, guía de tiempos y validación visual.
- [Literature Review](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/literature-review.md): Realiza revisiones bibliográficas sistemáticas y completas usando varias bases académicas (PubMed, arXiv, bioRxiv, Semantic Scholar). Genera markdown y PDF con citas verificadas en varios estilos (APA, Nature, Vancouver).
- [Infographics](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/infographics.md): Crea infografías profesionales con Nano Banana Pro AI y refinamiento iterativo inteligente. Usa Gemini 3.6 Flash para revisar la calidad e integra investigación con Perplexity Sonar. Soporta 10 tipos, 8 estilos y paletas para daltonismo.
- [Latex Posters](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/latex-posters.md): Crea pósteres de investigación profesionales en LaTeX con beamerposter, tikzposter o baposter, para conferencias y comunicación científica: layout, colores, columnas múltiples e integración de figuras.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)