K-Dense-AI/scientific-agent-skills / skills/pufferlib
pufferlib
VerifiedVersion-aware guidance for PufferLib reinforcement-learning environments, vectorization, policies, PuffeRL training, evaluation, and safe checkpoint review. Covers the native 5.0 build and environment API, published 3.0.0 Gymnasium/PettingZoo adaptation, and a pinned historical 4.0 profile.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.3 KB |
| references/environments.md | markdown | 10.7 KB |
| references/integration.md | markdown | 9.4 KB |
| references/native-5.md | markdown | 8.1 KB |
| references/policies.md | markdown | 7.2 KB |
| references/training.md | markdown | 13.0 KB |
| references/vectorization.md | markdown | 8.7 KB |
| scripts/__init__.py | script | 62 B |
| scripts/_common.py | script | 6.5 KB |
| scripts/benchmark_vectorization.py | script | 8.1 KB |
| scripts/env_contract_validator.py | script | 6.7 KB |
| scripts/env_template.py | script | 7.1 KB |
| scripts/inspect_checkpoint.py | script | 6.9 KB |
| scripts/repro_plan.py | script | 5.9 KB |
| scripts/train_template.py | script | 10.4 KB |
| scripts/validate_plan.py | script | 18.4 KB |
scripts/env_contract_validator.py
View on GitHub#!/usr/bin/env python3
"""Validate a built-in synthetic environment without importing plug-ins."""
from __future__ import annotations
import argparse
import math
import random
from typing import Any
try:
from ._common import UserInputError, bounded_int, emit_json
from .env_template import SyntheticGymEnv
except ImportError: # Direct script execution.
from _common import UserInputError, bounded_int, emit_json
from env_template import SyntheticGymEnv
def _require(condition: bool, message: str, errors: list[str]) -> None:
if not condition:
errors.append(message)
def _validate_reset(result: Any, env: SyntheticGymEnv, errors: list[str]) -> Any:
_require(
isinstance(result, tuple) and len(result) == 2,
"reset() must return (observation, info)",
errors,
)
if not isinstance(result, tuple) or len(result) != 2:
return None
observation, info = result
_require(
env.observation_space.contains(observation),
"reset observation is outside observation_space",
errors,
)
_require(isinstance(info, dict), "reset info must be a dict", errors)
return observation
def _validate_step(result: Any, env: SyntheticGymEnv, errors: list[str]) -> tuple[bool, bool]:
_require(
isinstance(result, tuple) and len(result) == 5,
"step() must return (observation, reward, terminated, truncated, info)",
errors,
)
if not isinstance(result, tuple) or len(result) != 5:
return False, False
observation, reward, terminated, truncated, info = result
_require(
env.observation_space.contains(observation),
"step observation is outside observation_space",
errors,
)
_require(
isinstance(reward, (int, float))
and not isinstance(reward, bool)
and math.isfinite(float(reward)),
"reward must be a finite scalar",
errors,
)
_require(type(terminated) is bool, "terminated must be bool", errors)
_require(type(truncated) is bool, "truncated must be bool", errors)
_require(isinstance(info, dict), "step info must be a dict", errors)
_require(
not (terminated and truncated),
"synthetic environment must not terminate and truncate simultaneously",
errors,
)
return bool(terminated), bool(truncated)
def _check_determinism(seed: int, max_steps: int, errors: list[str]) -> None:
env_a = SyntheticGymEnv(max_steps=max_steps)
env_b = SyntheticGymEnv(max_steps=max_steps)
first_a = env_a.reset(seed=seed)
first_b = env_b.reset(seed=seed)
_require(first_a == first_b, "same reset seed produced different results", errors)
actions = [0, 2, 1, 2, 0, 1]
for action in actions:
result_a = env_a.step(action)
result_b = env_b.step(action)
_require(result_a == result_b, "same action trace produced different results", errors)
if result_a[2] or result_a[3]:
break
env_a.close()
env_b.close()
def validate_synthetic(
*,
seed: int,
steps: int,
episodes: int,
max_steps: int,
) -> dict[str, Any]:
"""Run bounded API, space, reset, termination, and determinism checks."""
errors: list[str] = []
env = SyntheticGymEnv(max_steps=max_steps)
_require(hasattr(env, "observation_space"), "missing observation_space", errors)
_require(hasattr(env, "action_space"), "missing action_space", errors)
action_rng = random.Random(seed + 1)
observation = _validate_reset(env.reset(seed=seed), env, errors)
total_steps = 0
completed_episodes = 0
terminations = 0
truncations = 0
while total_steps < steps and completed_episodes < episodes:
action = env.action_space.sample(action_rng)
_require(env.action_space.contains(action), "sampled action is invalid", errors)
terminated, truncated = _validate_step(env.step(action), env, errors)
total_steps += 1
if terminated or truncated:
completed_episodes += 1
terminations += int(terminated)
truncations += int(truncated)
observation = _validate_reset(
env.reset(seed=seed + completed_episodes), env, errors
)
_require(
observation is None or env.observation_space.contains(observation),
"final observation is invalid",
errors,
)
_check_determinism(seed, max_steps, errors)
env.close()
return {
"checks": {
"deterministic_seed": "passed" if not errors else "see errors",
"reset_two_tuple": True,
"spaces": True,
"step_five_tuple": True,
},
"contract": "gymnasium",
"environment": "synthetic",
"errors": errors,
"network_used": False,
"observed": {
"episodes": completed_episodes,
"steps": total_steps,
"terminations": terminations,
"truncations": truncations,
},
"seed": seed,
"status": "passed" if not errors else "failed",
"vector_shape_expectation": {
"actions": ["num_envs"],
"observations": ["num_envs", 4],
"rewards": ["num_envs"],
"terminations": ["num_envs"],
"truncations": ["num_envs"],
},
}
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
description=(
"Validate only the allowlisted built-in synthetic environment; "
"external modules and dotted import paths are not supported."
)
)
parser.add_argument("--environment", choices=["synthetic"], default="synthetic")
parser.add_argument("--seed", type=int, default=42)
parser.add_argument("--steps", type=int, default=64, help="1..10000")
parser.add_argument("--episodes", type=int, default=8, help="1..100")
parser.add_argument("--max-steps", type=int, default=16, help="1..10000")
parser.add_argument("--compact", action="store_true")
return parser
def main(argv: list[str] | None = None) -> int:
parser = build_parser()
args = parser.parse_args(argv)
try:
steps = bounded_int(args.steps, name="steps", minimum=1, maximum=10_000)
episodes = bounded_int(args.episodes, name="episodes", minimum=1, maximum=100)
max_steps = bounded_int(
args.max_steps, name="max_steps", minimum=1, maximum=10_000
)
report = validate_synthetic(
seed=args.seed,
steps=steps,
episodes=episodes,
max_steps=max_steps,
)
except (UserInputError, ValueError, RuntimeError) as exc:
parser.error(str(exc))
emit_json(report, pretty=not args.compact)
return 0 if report["status"] == "passed" else 1
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |