@pikaa-ai/pikaa 0.2.5 → 0.3.1

package/skills/pufferlib/references/environments.md

@@ -0,0 +1,260 @@
+# Environment Contracts and Native Environments
+
+Research snapshot: **2026-07-23**.
+
+## Start from the Gymnasium contract
+
+A current single-agent Gymnasium environment defines `observation_space` and
+`action_space`, then implements:
+
+```python
+def reset(self, *, seed=None, options=None):
+    super().reset(seed=seed)
+    return observation, info
+
+def step(self, action):
+    return observation, reward, terminated, truncated, info
+```
+
+Contract requirements:
+
+- `observation` must be contained in `observation_space` after reset and every
+  step, with the documented shape and dtype.
+- `action` must be contained in `action_space`.
+- `reward` is a finite scalar for ordinary single-agent tasks.
+- `terminated` means the task's MDP reached a terminal state.
+- `truncated` means an external limit ended the episode, commonly a time limit.
+- `info` is a dictionary; never hide the only termination signal in it.
+- Call `reset()` after either `terminated` or `truncated`.
+- Seed the environment through `reset(seed=...)`. Seed the action space
+  separately when sampled actions must be reproducible.
+- Always call `close()`.
+
+Do not collapse `terminated` and `truncated` during learning. A time-limit
+truncation can still permit value bootstrapping; a true terminal state does not.
+
+Run the local contract tool before involving PufferLib:
+
+```bash
+python3 scripts/env_contract_validator.py
+```
+
+It validates only the bundled synthetic environment. It intentionally has no
+module-path option, so it cannot dynamically import an untrusted package.
+
+## Published PufferLib 3.0.0 native contract
+
+For a native Python `PufferEnv`, assign these attributes **before** calling
+`super().__init__(buf)`:
+
+```python
+import gymnasium
+import numpy as np
+import pufferlib
+
+
+class ReviewedEnv(pufferlib.PufferEnv):
+    def __init__(self, buf=None, seed=0):
+        self.single_observation_space = gymnasium.spaces.Box(
+            low=-1.0, high=1.0, shape=(4,), dtype=np.float32
+        )
+        self.single_action_space = gymnasium.spaces.Discrete(3)
+        self.num_agents = 2
+        super().__init__(buf)
+```
+
+The stable base accepts a Box observation space and Discrete, MultiDiscrete, or
+Box action space. It allocates or attaches:
+
+- `observations`
+- `actions`
+- `rewards`
+- `terminals`
+- `truncations`
+- `masks`
+
+Native methods operate on those buffers:
+
+```python
+def reset(self, seed=None):
+    # update self.observations in place
+    return self.observations, []
+
+def step(self, actions):
+    # update all buffers in place
+    return (
+        self.observations,
+        self.rewards,
+        self.terminals,
+        self.truncations,
+        [],
+    )
+```
+
+The `infos` value for native Puffer environments is a list of dictionaries.
+PufferLib's native interface expects vector rows for agents, even when there is
+one agent. Native environments handle their own resets; clear rewards,
+terminals, truncations, masks, and partially written observations explicitly.
+Never leave a previous step's buffer values in place.
+
+### Native shape checklist
+
+For `A = num_agents` and single observation shape `S`:
+
+- observations: `(A, *S)`
+- rewards: `(A,)`
+- terminals: `(A,)`
+- truncations: `(A,)`
+- masks: `(A,)`
+- actions: joint shape derived from the single action space and `A`
+
+Validate the exact allocated action shape rather than assuming `(A,)`, especially
+for MultiDiscrete and Box actions.
+
+## Stable Gymnasium and PettingZoo adaptation
+
+PufferLib 3.0 uses explicit adapters:
+
+```python
+import pufferlib.emulation
+
+wrapped = pufferlib.emulation.GymnasiumPufferEnv(reviewed_gymnasium_instance)
+```
+
+or:
+
+```python
+wrapped = pufferlib.emulation.PettingZooPufferEnv(reviewed_parallel_instance)
+```
+
+There is no supported 3.0 `pufferlib.emulate(...)` convenience function matching
+the old skill examples. Pass either an `env` instance or an `env_creator`
+callable according to the class signature; do not pass both.
+
+The Gymnasium adapter:
+
+- maps structured observation/action spaces to flat arrays;
+- checks the first observation and action against the original spaces;
+- returns separate terminal and truncation values;
+- requires reset before step and reset after episode end.
+
+The PettingZoo adapter:
+
+- targets the Parallel API;
+- uses `possible_agents` as the fixed slot set;
+- pads missing agents and exposes masks;
+- canonicalizes per-agent spaces and flattened buffers.
+
+Validate heterogeneous-agent spaces before use. The adapter derives its single
+spaces from the first possible agent, so environments with incompatible spaces
+need an explicit reviewed transformation.
+
+### Structured spaces
+
+Stable emulation supports Box, Discrete, MultiDiscrete, Tuple, and Dict patterns
+through a packed NumPy dtype. This is byte-layout conversion, not semantic
+feature engineering. Check:
+
+- deterministic Dict key order;
+- leaf shape and dtype;
+- finite numeric values;
+- lossless action reconstruction;
+- policy-side unflattening;
+- padding/mask handling for variable populations.
+
+## Current 4.0 Ocean contract
+
+The 4.0 default branch focuses on first-party C environments. It no longer
+provides the 3.0 Python emulation/vector modules. The official starting points
+are:
+
+- `ocean/squared`: commented single-agent template
+- `ocean/target`: commented multi-agent template
+
+A binding defines compile-time metadata such as:
+
+```c
+#define OBS_SIZE 121
+#define NUM_ATNS 1
+#define ACT_SIZES {5}
+#define OBS_TENSOR_T ByteTensor
+
+#define Env Squared
+#include "vecenv.h"
+```
+
+The environment struct must include pointers for observations, actions,
+rewards, and terminals, plus `num_agents` and a log struct. It implements
+`c_reset`, `c_step`, `c_render`, and `c_close`; `binding.c` supplies `my_init`
+and `my_log`.
+
+Security and correctness rules:
+
+1. Treat the C environment and every linked library as native code.
+2. Verify repository/commit, license, asset rights, and checksums before build.
+3. Build only the selected environment in a disposable container or VM.
+4. Start with the local/address-sanitizer build described by upstream.
+5. Match `OBS_SIZE`, tensor dtype, action branch count/sizes, and actual writes.
+6. Bounds-check every index and allocation; use checked arithmetic for sizes.
+7. Initialize every output element each step. Reset reward/terminal buffers
+   before early returns.
+8. Use an environment-owned RNG seeded per instance; do not use global RNG
+   state for reproducibility.
+9. Free only memory owned by the environment. Do not free framework buffers.
+10. Fuzz reset/step/action boundaries before optimization.
+
+`c_step` may reset immediately after marking a terminal. Record this autoreset
+behavior when interpreting terminal observations.
+
+## Environment provenance
+
+An environment package may execute arbitrary Python/native code and may fetch
+assets at import, build, reset, or render time. Before execution:
+
+- use the official repository and immutable revision;
+- inspect package/build scripts and transitive dependencies;
+- verify artifact hashes or attestations;
+- review license compatibility for code, datasets, media, ROMs, maps, and model
+  opponents separately;
+- reject unlicensed ROMs or “accept ROM license” automation without proof of
+  rights;
+- disable network and credentials in the first-run sandbox;
+- cap disk, memory, processes, threads, episode length, agents, and render size;
+- do not load bundled checkpoints or pickle files during environment import.
+
+An entry in Ocean/config is not a blanket security, quality, or licensing
+approval.
+
+## Testing ladder
+
+1. Built-in synthetic contract validator.
+2. One environment, one seed, serial, tens of steps.
+3. Boundary actions and intentionally invalid actions.
+4. Termination and time-limit truncation tests.
+5. Same-seed trace comparison.
+6. Independent-seed diversity check.
+7. Structured-space round trip.
+8. Multi-agent join/leave and mask tests.
+9. Serial versus vectorized trace equivalence where ordering permits.
+10. Bounded throughput benchmark only after correctness passes.
+
+## Sources
+
+- [Gymnasium Env API](https://gymnasium.farama.org/api/env/) — current reset,
+  step, spaces, and seeding contract; accessed 2026-07-23.
+- [Gymnasium terminated/truncated explanation](https://farama.org/Gymnasium-Terminated-Truncated-Step-API)
+  — published 2023-10-27; accessed 2026-07-23.
+- [PufferLib 3.0 core environment source](https://github.com/PufferAI/PufferLib/blob/3.0/pufferlib/pufferlib.py)
+  — stable native contract; 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 Gymnasium example](https://github.com/PufferAI/PufferLib/blob/3.0/examples/gymnasium_env.py)
+  — stable example; accessed 2026-07-23.
+- [PufferLib 3.0 PettingZoo example](https://github.com/PufferAI/PufferLib/blob/3.0/examples/pettingzoo_env.py)
+  — stable example; accessed 2026-07-23.
+- [PufferLib 4.0 Squared template](https://github.com/PufferAI/PufferLib/tree/4.0/ocean/squared)
+  — current single-agent native template; accessed 2026-07-23.
+- [PufferLib 4.0 Target template](https://github.com/PufferAI/PufferLib/tree/4.0/ocean/target)
+  — current multi-agent native template; accessed 2026-07-23.
+- [PufferLib Ocean](https://puffer.ai/ocean.html) — current first-party
+  collection; accessed 2026-07-23.

package/skills/pufferlib/references/integration.md

@@ -0,0 +1,192 @@
+# 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

@@ -0,0 +1,181 @@
+# 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.