@pikaa-ai/pikaa 0.3.1 → 0.3.5

package/skills/pufferlib/references/integration.md

@@ -1,192 +0,0 @@
-# Integration, Security, and Migration Guide
-
-Research snapshot: **2026-07-23**.
-
-## Compatibility matrix
-
-| Need | Published `pufferlib==3.0.0` | Current `4.0` source |
-|---|---|---|
-| Gymnasium instance adaptation | `pufferlib.emulation.GymnasiumPufferEnv` | Removed from current source |
-| PettingZoo Parallel adaptation | `pufferlib.emulation.PettingZooPufferEnv` | Removed from current source |
-| Python vector backends | `pufferlib.vector` | Removed from current source |
-| Native Python `PufferEnv` | Supported | Replaced by current C/Ocean interface |
-| Trainer | `pufferlib.pufferl.PuffeRL` | Native backend or `pufferlib.torch_pufferl.PuffeRL` |
-| External logging | W&B and Neptune | W&B in current CLI |
-| Primary config | merged INI sections | different INI schema |
-| Checkpoints | Torch state dict plus trainer state | native `.bin`; Torch fallback state dict |
-
-Pin a profile. Do not import from a floating branch or blend examples across
-columns.
-
-## Correct stable adaptation patterns
-
-### Gymnasium
-
-```python
-import gymnasium
-import pufferlib.emulation
-import pufferlib.vector
-
-
-def make_env():
-    raw = gymnasium.make("CartPole-v1")
-    return pufferlib.emulation.GymnasiumPufferEnv(raw)
-
-
-vecenv = pufferlib.vector.make(
-    make_env,
-    backend=pufferlib.vector.Serial,
-    num_envs=2,
-    seed=42,
-)
-try:
-    observations, infos = vecenv.reset(seed=42)
-    actions = vecenv.action_space.sample()
-    observations, rewards, terminals, truncations, infos = vecenv.step(actions)
-finally:
-    vecenv.close()
-```
-
-This example is an API pattern, not authorization to install or execute
-`CartPole-v1` or another plug-in. Review the exact environment and dependencies
-first.
-
-### PettingZoo
-
-Use a reviewed Parallel environment instance:
-
-```python
-wrapped = pufferlib.emulation.PettingZooPufferEnv(reviewed_parallel_env)
-```
-
-The stable source does not document automatic AEC-to-Parallel conversion in
-this adapter. Convert explicitly with PettingZoo's supported utilities only
-when the environment's turn semantics permit it, then test action ordering,
-dead-agent handling, masks, and termination/truncation dictionaries.
-
-### Native stable environment
-
-Subclass `pufferlib.PufferEnv`, define `single_observation_space`,
-`single_action_space`, and `num_agents` before `super().__init__`, then update
-the provided arrays in place. Native Puffer environments are already vector
-interfaces; do not return Gym's scalar four-tuple.
-
-## Unsupported shortcuts from the old skill
-
-Remove or migrate these historical patterns:
-
-| Historical pattern | Current guidance |
-|---|---|
-| `pufferlib.make("name", ...)` | Stable: import an audited creator and use `pufferlib.vector.make`; 4.0: build/configure a named native environment |
-| `pufferlib.emulate(...)` | Stable: instantiate `GymnasiumPufferEnv` or `PettingZooPufferEnv` explicitly |
-| `pufferlib.vectorization.Serial` | Stable module is `pufferlib.vector.Serial` |
-| `from pufferlib import PuffeRL` | Stable trainer is `pufferlib.pufferl.PuffeRL`; 4.0 fallback is in `torch_pufferl` |
-| define native `observation_space`/`action_space` | Stable native class requires `single_observation_space`/`single_action_space` before `super()` |
-| return `(obs, reward, done, info)` | Return separate termination and truncation values |
-| native multi-agent dictionaries and `dones["__all__"]` | Use stable vector buffers or a reviewed PettingZoo Parallel adapter |
-| arbitrary dotted `entry_point` registration | Import an audited callable directly; bundled tools reject dotted paths |
-| top-level `WandbLogger`/`NeptuneLogger` | Stable logger classes live in `pufferlib.pufferl`; prefer the CLI and sanitized config |
-| assume Atari/Procgen/NetHack names exist everywhere | Verify the chosen version's config/source and install the separately reviewed environment |
-
-## Migrating 3.0 to 4.0
-
-This is a redesign, not a drop-in upgrade:
-
-1. Preserve the 3.0 lock, source digest, config, checkpoint hashes, and baseline
-   evaluation before changing anything.
-2. Inventory use of `emulation`, `vector`, `PufferEnv`, third-party environments,
-   policy wrappers, INI keys, logger flags, and Torch checkpoints.
-3. Decide whether the application should stay on published 3.0.0 or port to a
-   native 4.0 C environment. The current docs say the Python/third-party layer
-   was removed from 4.0.
-4. Port environment logic to the reviewed Squared/Target C binding contract.
-5. Recreate configuration using 4.0 `[vec]`, `[policy]`, `[torch]`, and `[train]`
-   keys. Do not mechanically rename old keys.
-6. Rebuild policy composition around 4.0 encoder/decoder/network modules or the
-   native backend.
-7. Treat old `.pt` and new `.bin` files as incompatible unless an official,
-   tested converter says otherwise. Do not improvise binary conversion.
-8. Re-run contract, same-seed trace, throughput, and held-out learning
-   baselines. Attribute behavior changes; do not compare headline SPS alone.
-
-The default branch contains some stale 3.0-style examples even though the
-corresponding modules are absent. Prefer current implementation and docs over
-those copied examples.
-
-## Third-party environments and native code
-
-Environment extras can pull old Gym versions, native libraries, renderers,
-emulators, datasets, model opponents, and ROM tooling. A package name in a
-PufferLib optional extra is not a security or license endorsement.
-
-Before install/import/build:
-
-1. Identify the official repository and immutable revision.
-2. Read build/install hooks and all network downloads.
-3. Verify licenses for code and assets separately.
-4. Verify hashes/attestations; record missing provenance.
-5. Use a disposable sandbox without credentials, home-directory mounts, or
-   network after required artifacts are staged.
-6. Cap processes, threads, memory, disk, render resolution, agents, and steps.
-7. Do not execute bundled native extensions, ROMs, checkpoints, or pickle files
-   until separately trusted.
-
-For Atari and similar systems, the user must supply legally obtained assets.
-Never download ROM sets or auto-accept a license on the user's behalf.
-
-## Logging integration
-
-External tracking is disabled by default. The stable logger implementations can
-log the full argument mapping and can upload model artifacts. Therefore:
-
-- sanitize arguments before logger construction;
-- keep `WANDB_API_KEY` and `NEPTUNE_API_TOKEN` only in an approved environment
-  injection or secret manager;
-- never add credential keys to nested INI/JSON/config objects;
-- do not pass a token on the command line;
-- disable model/source upload unless explicitly approved;
-- review project visibility, retention, residency, access controls, and cost;
-- use vendor offline/disabled modes only after confirming what is written
-  locally and how later sync behaves.
-
-Do not print all environment variables or recursively discover `.env` files.
-Checking whether one explicitly named credential variable exists can be
-acceptable; reading or logging its value is not.
-
-## Integration acceptance test
-
-For each reviewed environment/profile:
-
-1. Create one instance without network or GPU.
-2. Validate spaces and reset return.
-3. Step a fixed action trace until both ordinary and episode-end paths run.
-4. Verify terminated/truncated semantics and final observation behavior.
-5. Close and confirm no child processes/resources remain.
-6. Run stable Serial or one 4.0 local native instance.
-7. Compare a same-seed trace.
-8. Scale to two workers/threads with small caps.
-9. Run policy shape and finite-value checks.
-10. Run held-out evaluation with logging still disabled.
-
-Only then consider GPU training, external logging, or larger parallelism.
-
-## Sources
-
-- [PufferLib PyPI 3.0.0](https://pypi.org/project/pufferlib/3.0.0/) —
-  published 2025-06-23; accessed 2026-07-23.
-- [PufferLib 3.0 emulation source](https://github.com/PufferAI/PufferLib/blob/3.0/pufferlib/emulation.py)
-  — stable adapters; accessed 2026-07-23.
-- [PufferLib 3.0 vector source](https://github.com/PufferAI/PufferLib/blob/3.0/pufferlib/vector.py)
-  — stable vector API; accessed 2026-07-23.
-- [PufferLib 3.0 trainer source](https://github.com/PufferAI/PufferLib/blob/3.0/pufferlib/pufferl.py)
-  — stable logger/checkpoint behavior; accessed 2026-07-23.
-- [PufferLib 4.0 package tree](https://github.com/PufferAI/PufferLib/tree/4.0/pufferlib)
-  — current modules; accessed 2026-07-23.
-- [PufferLib 4.0 docs](https://puffer.ai/docs.html) — current architecture and
-  removal note; accessed 2026-07-23.
-- [PufferLib releases](https://github.com/PufferAI/PufferLib/releases) —
-  checked for source releases on 2026-07-23.
-- [Gymnasium Env API](https://gymnasium.farama.org/api/env/) — current
-  single-agent contract; accessed 2026-07-23.
-- [PyTorch security policy](https://github.com/pytorch/pytorch/security) —
-  model/native-package safety; accessed 2026-07-23.

package/skills/pufferlib/references/policies.md

@@ -1,181 +0,0 @@
-# Policies and Model Contracts
-
-Research snapshot: **2026-07-23**. Policy APIs changed substantially between
-published PufferLib 3.0.0 and current 4.0 source.
-
-## Published 3.0.0
-
-PufferLib 3.0 policies are ordinary `torch.nn.Module` objects. The environment
-exposes `single_observation_space` and `single_action_space`; size heads from
-those single-agent spaces, not from the batched spaces.
-
-### Minimal feed-forward policy
-
-Build an `nn.Module` with an encoder sized from
-`env.single_observation_space.shape`, an action head sized from
-`env.single_action_space`, and a one-value critic head. The official stable
-example defines a rollout method named `forward_eval(observations, state=None)`
-and makes the normal `forward` method use the same contract. Here, `forward_eval`
-is a PufferLib/PyTorch method name; it does **not** invoke Python's dangerous
-`eval()` builtin.
-
-For a discrete action space, the first output contains action logits and the
-second is the value estimate. Preserve the leading agent-batch dimension.
-
-### Recurrent composition
-
-The stable `pufferlib.models.LSTMWrapper` expects a base policy with:
-
-```python
-def encode_observations(self, observations, state=None):
-    ...
-
-def decode_actions(self, hidden):
-    ...
-```
-
-The wrapper uses an `LSTMCell` during rollout inference and an `LSTM` over
-time-batched data during training. Do not manually reshape recurrent state
-without checking the source's batch/time convention. Reset hidden state on
-actual terminations and truncations according to the trainer's mask behavior.
-
-### Structured observations
-
-Stable emulation flattens `Dict` and `Tuple` spaces into a homogeneous array.
-The byte layout is described by `env.emulated`. In policy setup:
-
-```python
-native_dtype = pufferlib.pytorch.nativize_dtype(env.emulated)
-```
-
-In the forward pass:
-
-```python
-structured = pufferlib.pytorch.nativize_tensor(observations, native_dtype)
-```
-
-Keep the original flattened dtype. Constructing a new float tensor before
-unflattening can destroy the packed representation. Validate every recovered
-leaf shape and dtype before training.
-
-### Action spaces
-
-The 3.0 source handles:
-
-- `Discrete`: one categorical logits tensor.
-- `MultiDiscrete`: one logits tensor per action branch.
-- `Box`: a Normal distribution path for continuous actions.
-
-Do not infer support from the 2024 paper's limitations section; that paper
-describes an earlier release. Test clipping/scaling against the environment's
-actual `Box.low`, `Box.high`, shape, and dtype. A `tanh` output is not a general
-substitute for affine mapping to arbitrary bounds.
-
-### Stable model utilities
-
-Useful 3.0 symbols include:
-
-- `pufferlib.pytorch.layer_init`
-- `pufferlib.pytorch.nativize_dtype`
-- `pufferlib.pytorch.nativize_tensor`
-- `pufferlib.models.Default`
-- `pufferlib.models.LSTMWrapper`
-- `pufferlib.models.Convolutional`
-- `pufferlib.models.ProcgenResnet`
-
-Inspect the exact 3.0 source before copying signatures. Do not use top-level
-`from pufferlib import PuffeRL`; the trainer is
-`pufferlib.pufferl.PuffeRL`.
-
-## Current 4.0 source
-
-The current PyTorch fallback composes a policy from three modules:
-
-```python
-policy = pufferlib.models.Policy(
-    encoder=encoder,
-    decoder=decoder,
-    network=network,
-)
-```
-
-The source contract is:
-
-- `Policy.initial_state(batch_size, device)`
-- `Policy.forward_eval(x, state)` for rollout inference
-- `Policy.forward(x)` for time-batched training
-- encoder maps observations to hidden vectors
-- recurrent/network module maps hidden vectors and state
-- decoder maps hidden vectors to action logits and values
-
-Current built-ins include `DefaultEncoder`, `DefaultDecoder`, `MLP`, `MinGRU`,
-`LSTM`, `GRU`, `NatureEncoder`, and `ImpalaEncoder`. INI config selects the
-Torch fallback components:
-
-```ini
-[torch]
-network = MinGRU
-encoder = DefaultEncoder
-decoder = DefaultDecoder
-
-[policy]
-hidden_size = 128
-num_layers = 4
-```
-
-The default 4.0 backend is the native implementation, not this Torch fallback.
-The CLI flag `--slowly` selects the fallback.
-
-## Shape and numerical checks
-
-Run these checks before a long job:
-
-1. Reset the reviewed environment and record observation shape/dtype/range.
-2. Run one policy inference under `torch.no_grad()`.
-3. For discrete actions, require logits shape
-   `(agent_batch, action_space.n)`.
-4. Require values to represent one scalar per active agent.
-5. For `MultiDiscrete`, verify branch count and each branch width.
-6. For recurrent policies, verify state batch matches active agent rows and
-   that masks reset state at episode boundaries.
-7. Reject NaN/Infinity in observations, logits, values, losses, and gradients.
-8. Confirm inactive/padded multi-agent rows do not contribute to loss.
-9. Run backward once and verify finite, non-missing gradients.
-10. Compare eager and compiled outputs before enabling compilation.
-
-`torch.compile` and reduced precision can alter performance and numerical
-behavior. Record PyTorch, CUDA, compiler mode, precision, and deterministic
-settings. Do not claim determinism solely because seeds are fixed.
-
-## Checkpoint-safe policy workflow
-
-- Save weights/state dictionaries, architecture config, environment revision,
-  package lock, seed, and checksum separately.
-- Do not serialize arbitrary policy objects.
-- Never call `torch.load` on an untrusted file. PufferLib 3.0 and the 4.0 Torch
-  fallback use `torch.load` for model paths; provenance review is therefore a
-  precondition, not an optional cleanup.
-- Inspect metadata first with `scripts/inspect_checkpoint.py`; it never imports
-  Torch or deserializes.
-- Verify an expected SHA-256 and license before loading.
-- If business requirements force inspection of an untrusted model, isolate the
-  operation in a disposable sandbox with no credentials, network, host mounts,
-  or sensitive data. PyTorch warns that models are programs and that even
-  inspection tools may execute model code.
-
-## Sources
-
-- [PufferLib 3.0 policy example](https://github.com/PufferAI/PufferLib/blob/3.0/examples/pufferl.py)
-  — stable example; accessed 2026-07-23.
-- [PufferLib 3.0 PyTorch utilities](https://github.com/PufferAI/PufferLib/blob/3.0/pufferlib/pytorch.py)
-  — stable implementation; accessed 2026-07-23.
-- [PufferLib 3.0 models](https://github.com/PufferAI/PufferLib/blob/3.0/pufferlib/models.py)
-  — stable model classes; accessed 2026-07-23.
-- [PufferLib 4.0 models](https://github.com/PufferAI/PufferLib/blob/4.0/pufferlib/models.py)
-  — current source model contract; accessed 2026-07-23.
-- [PufferLib 4.0 Torch trainer](https://github.com/PufferAI/PufferLib/blob/4.0/pufferlib/torch_pufferl.py)
-  — current fallback and checkpoint loading; accessed 2026-07-23.
-- [PyTorch security policy](https://github.com/pytorch/pytorch/security) —
-  untrusted-model guidance; accessed 2026-07-23.
-- [PyTorch `torch.load` documentation](https://docs.pytorch.org/docs/stable/generated/torch.load.html)
-  — deserialization warning; accessed 2026-07-23.

package/skills/pufferlib/references/training.md

@@ -1,287 +0,0 @@
-# Training, Evaluation, Configuration, and Logging
-
-Research snapshot: **2026-07-23**.
-
-## Choose a version profile first
-
-### Published stable package
-
-PyPI's latest stable `pufferlib` release is **3.0.0**, published
-**2025-06-23**. It declares Python `>=3.9` and is distributed only as a
-60.7 MB source archive:
-
-```text
-pufferlib-3.0.0.tar.gz
-sha256: 7df3a3e3f5f894d78d2a1f5374097890aec01473183e748abefe4f3faa10eaa9
-```
-
-The uploaded metadata depends on NumPy `<2.0`, Gym `<=0.23`, Gymnasium
-`<=0.29.1`, PettingZoo `<=1.24.1`, Shimmy, Torch, Neptune, W&B, and other
-packages without a complete transitive lock. It does not declare a CUDA
-version or a minimum Torch version. Do not invent compatibility guarantees.
-
-### Current source line
-
-The upstream default branch is `4.0`; its `pyproject.toml` says version `4.0.0`,
-Python `>=3.10`, and Torch `>=2.9`. As of the research date, this source line
-is not the latest stable PyPI artifact.
-
-The current PufferTank Dockerfile uses:
-
-- Ubuntu 24.04
-- NVIDIA CUDA `13.0.2` cuDNN development image
-- Python 3.12
-- the CUDA 13.0 PyTorch wheel index
-- Nsight Systems `2025.6.3`
-
-The Dockerfile does **not** pin an exact Torch wheel, uv version, PufferLib
-commit, or every apt package. It is an upstream convenience environment, not a
-complete reproducibility lock.
-
-## Reproducible uv workflow
-
-Do not use an unpinned `uv pip install pufferlib`. Work in a disposable,
-project-specific environment and commit `pyproject.toml` plus `uv.lock`.
-
-For the published profile, after reviewing the source archive and build:
-
-```bash
-uv venv --python 3.11
-uv add --exact --no-sync "pufferlib==3.0.0"
-uv lock
-uv sync --frozen
-```
-
-Confirm the lock records the published SHA-256 above and review every resolved
-dependency. The 3.0.0 source build can compile native code and may fetch build
-assets. Resolve and build in a sandbox with no credentials or sensitive mounts.
-Do not treat a successful resolver run as a security review.
-
-For 4.0 source work, pin an immutable revision rather than branch `4.0`:
-
-```bash
-uv add --no-sync \
-  "pufferlib @ git+https://github.com/PufferAI/PufferLib.git@25647630e1b15330bb3153a5a0d3ff8d234c3acf"
-uv lock
-```
-
-The commit above is the reviewed 4.0 branch head on 2026-07-23. Re-review before
-updating it. Native training still requires an audited build of a specific
-environment; uv locking does not lock compilers, CUDA, NCCL, cuDNN, Raylib, or
-system libraries.
-
-Never run remote install scripts directly from a pipe. Download, inspect, pin,
-verify, and execute only in an appropriate sandbox.
-
-## Published 3.0.0 training
-
-### CLI
-
-The 3.0 console entry point is `puffer = pufferlib.pufferl:main`:
-
-```bash
-puffer train ENV_NAME [OPTIONS]
-puffer eval ENV_NAME [OPTIONS]
-puffer sweep ENV_NAME [OPTIONS]
-puffer autotune ENV_NAME [OPTIONS]
-puffer profile ENV_NAME [OPTIONS]
-puffer export ENV_NAME [OPTIONS]
-```
-
-Environment, vector, policy, recurrent, training, and sweep values come from
-INI sections. Overrides use section-qualified flags:
-
-```bash
-puffer train puffer_breakout \
-  --train.device cpu \
-  --train.total-timesteps 100000 \
-  --vec.backend Serial \
-  --vec.num-envs 2
-```
-
-Run `puffer train ENV_NAME --help` against the exact locked environment because
-available options are generated from merged INI files.
-
-### Python API
-
-The stable trainer is `pufferlib.pufferl.PuffeRL`, not a top-level
-`pufferlib.PuffeRL`:
-
-```python
-from pufferlib import pufferl
-
-args = pufferl.load_config("puffer_breakout")
-vecenv = pufferl.load_env("puffer_breakout", args)
-policy = pufferl.load_policy(args, vecenv, "puffer_breakout")
-trainer = pufferl.PuffeRL(args["train"], vecenv, policy)
-
-try:
-    while trainer.epoch < trainer.total_epochs:
-        trainer.evaluate()
-        trainer.train()
-        trainer.mean_and_log()
-finally:
-    trainer.close()
-```
-
-The exact public methods include `evaluate`, `train`, `mean_and_log`,
-`save_checkpoint`, `print_dashboard`, and `close`. Use the CLI when possible;
-the Python trainer is a relatively low-level implementation surface.
-
-### Stable configuration checks
-
-- Make rollout/batch relationships explicit; do not rely on `auto` in a
-  published experiment.
-- Record environment, vector, policy, recurrent, and train sections verbatim.
-- Fix `seed` in both `[vec]` and `[train]`, then run multiple independent seeds.
-- Record `torch_deterministic`, precision, compile settings, optimizer, horizon,
-  minibatch, and total timesteps.
-- Keep evaluation seeds, instances, and metrics separate from training.
-
-## Current 4.0 training
-
-Build one audited environment, then use:
-
-```bash
-puffer train breakout
-puffer eval breakout --load-model-path checkpoints/.../weights.bin
-puffer sweep breakout
-puffer match breakout \
-  --load-model-path trusted-a.bin \
-  --load-enemy-model-path trusted-b.bin
-```
-
-Current modes are `train`, `eval`, `sweep`, `paretosweep`, and `match`.
-Native training is the default. `--slowly` selects the Torch fallback.
-Configuration uses sections such as:
-
-```ini
-[vec]
-total_agents = 4096
-num_buffers = 2
-num_threads = 16
-
-[train]
-total_timesteps = 10_000_000
-minibatch_size = 8192
-horizon = 64
-
-[torch]
-network = MinGRU
-encoder = DefaultEncoder
-decoder = DefaultDecoder
-```
-
-Current source validates that `minibatch_size` is divisible by `horizon` and
-does not exceed `horizon * total_agents`. Multi-GPU launch uses spawn. Do a
-small CPU/local build and contract test before CUDA training.
-
-## Held-out evaluation
-
-Training rollouts are not evaluation. For every reported result:
-
-1. Freeze one checkpoint-selection rule before inspecting held-out scores.
-2. Construct fresh evaluation environment instances.
-3. Use evaluation seeds disjoint from training seeds.
-4. Disable optimizer updates, exploration noise unless explicitly measuring it,
-   curriculum updates, normalization-stat updates, and reward shaping used only
-   for training.
-5. Report deterministic and stochastic policy protocols separately.
-6. Run enough episodes for uncertainty; report per-seed results and aggregate
-   intervals, not only a best run.
-7. Preserve terminated versus truncated semantics in return/length accounting.
-8. Record wrappers, frame skip, autoreset mode, opponent pool, policy state
-   reset, and rendering state.
-
-Generate a starting plan:
-
-```bash
-python3 scripts/repro_plan.py --environment synthetic
-```
-
-## Checkpoints
-
-PufferLib 3.0 saves a policy `state_dict` with `torch.save` and a separate
-trainer state containing optimizer state, global step, epoch, and run ID. Its
-loading paths call `torch.load`. The 4.0 native backend writes `.bin` weight
-files; the 4.0 Torch fallback also uses `torch.save`/`torch.load`.
-
-Rules:
-
-- Never load an untrusted checkpoint, even to “inspect” it.
-- Record SHA-256, size, source URL, immutable revision, license, environment,
-  policy architecture, package lock, and training config in a strict JSON
-  sidecar.
-- Do not use `latest` in a reproducible run; resolve and record the exact path
-  and digest.
-- Do not auto-download a run artifact by ID.
-- Test restore and evaluation in a disposable environment before a long resume.
-- A model-only checkpoint is not a bitwise resume; optimizer, scheduler,
-  normalizer, RNG, environment, and recurrent state may also matter.
-
-Safe metadata inspection:
-
-```bash
-python3 scripts/inspect_checkpoint.py trusted/model.pt \
-  --expected-sha256 EXPECTED_DIGEST
-```
-
-The helper hashes and classifies bytes only. It never imports Torch, invokes
-pickle, opens archive members, or extracts files.
-
-## External logging
-
-Local logging is the default. W&B and Neptune are optional network services
-that may transmit configuration, metrics, source metadata, hardware telemetry,
-stdout/stderr, and explicitly uploaded checkpoints/artifacts. They can create
-storage, seat, compute, or retention costs and are subject to vendor privacy,
-access, and retention policies.
-
-Credential rules:
-
-- W&B: use the named environment variable `WANDB_API_KEY` or an approved secret
-  manager.
-- Neptune: use `NEPTUNE_API_TOKEN` or an approved secret manager.
-- Never pass either secret as a CLI argument, INI/JSON value, logger config,
-  tag, run name, or chat/tool input.
-- Never print the value or include it in a broad environment dump.
-- Do not recursively search for `.env` files. If policy permits a local secret
-  file, read only the explicitly named key from the explicitly named file.
-- Sanitize configuration before logging; reject keys containing token, secret,
-  password, credential, authorization, private key, or API key.
-- Disable checkpoint/source upload unless separately approved.
-
-PufferLib 3.0 supports both `--wandb` and `--neptune`; its sweep mode requires
-one. Current 4.0 source exposes W&B but no Neptune CLI integration. In either
-profile, require explicit logging opt-in and disclosure acknowledgment. The
-bundled training planner enforces this without reading credential values:
-
-```bash
-python3 scripts/train_template.py \
-  --logger wandb \
-  --enable-external-logging \
-  --acknowledge-external-disclosure
-```
-
-## Sources
-
-- [PyPI: pufferlib 3.0.0](https://pypi.org/project/pufferlib/3.0.0/) —
-  released 2025-06-23; accessed 2026-07-23.
-- [PyPI 3.0.0 JSON metadata](https://pypi.org/pypi/pufferlib/3.0.0/json) —
-  package requirements and digest; accessed 2026-07-23.
-- [PufferLib 3.0 trainer](https://github.com/PufferAI/PufferLib/blob/3.0/pufferlib/pufferl.py)
-  — stable CLI, logger, and checkpoint source; accessed 2026-07-23.
-- [PufferLib 3.0 default config](https://github.com/PufferAI/PufferLib/blob/3.0/pufferlib/config/default.ini)
-  — stable parameters; accessed 2026-07-23.
-- [PufferLib 4.0 docs](https://puffer.ai/docs.html) — current CLI and
-  architecture; accessed 2026-07-23.
-- [PufferLib 4.0 trainer](https://github.com/PufferAI/PufferLib/blob/4.0/pufferlib/pufferl.py)
-  — current modes/config/checkpoints; accessed 2026-07-23.
-- [PufferLib 4.0 package metadata](https://github.com/PufferAI/PufferLib/blob/4.0/pyproject.toml)
-  — current Python/Torch requirements; accessed 2026-07-23.
-- [PufferTank 4.0 Dockerfile](https://github.com/PufferAI/PufferTank/blob/4.0/puffertank.dockerfile)
-  — CUDA/Python reference environment; accessed 2026-07-23.
-- [Neptune Run API](https://docs.neptune.ai/run) — token and offline-mode
-  guidance; accessed 2026-07-23.
-- [W&B documentation](https://docs.wandb.ai/) — logging and credential
-  guidance; accessed 2026-07-23.