PufferLib

Escolha a versão antes de escolher uma API. Revisado em 2026-10-01:

Para a 5.0, leia references/native-5.md. A revisão revisada é 6ffa5b10dbbbe4d1e8288367c7d9d3acd3bad4a2. Sua CLI é ./puffer train após a construção de um ambiente, não puffer train ENV_NAME. Não há emulação/API vetorial Python 5.0 ou fallback --slowly.

O esquema de plano agrupado suporta deliberadamente apenas 3.0 e 4.0 fixado; ele não inicia o treinamento. Todos os exemplos de treinamento nativos/PufferLib são revisados pelo código-fonte, ilustrativos e não executados nesta revisão. Verificações sintéticas agrupadas são testes de CPU executados, não evidências da instalação do PufferLib ou da qualidade do aprendizado. O sdist do PyPI foi verificado por hash e suas fontes Python inspecionadas; o branch 3.0 em movimento difere, incluindo seus contratos de load_policy e logger.

Padrões seguros

1. Comece com ferramentas sintéticas agrupadas, apenas CPU, sem rede.
2. Não importe um ambiente arbitrário por caminho pontuado. Ferramentas agrupadas aceitam apenas built-ins permitidos e identificadores slug.
3. Não instale ou execute um pacote de ambiente não revisado, extensão nativa, ROM, mapa, checkpoint ou arquivo pickle.
4. Verifique o código-fonte oficial, a revisão imutável, as licenças, os checksums ou as atestações e os hooks de compilação. Isole compilações nativas e a primeira execução.
5. Limite etapas, ambientes, agentes, workers, threads, buffers, memória, disco, tamanho de renderização e tempo de parede.
6. Mantenha os ambientes/seeds de treinamento e avaliação separados.
7. Defina o logging para local/nenhum por padrão. O logging externo requer opt-in explícito, reconhecimento de divulgação e aprovação separada de upload de artefatos.
8. Nunca passe credenciais W&B ou Neptune via CLI, INI, JSON, tags, nomes de execução ou configuração de logger. Nunca as imprima.
9. Nunca descarregue todas as variáveis de ambiente ou procure recursivamente por .env.
10. Faça hash dos bytes do checkpoint antes do carregamento confiável e isolado; a inspeção de metadados não é prova de segurança.

Primeiras verificações locais

Todas as CLIs agrupadas são independentes de dependências e emitem JSON estrito:

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

Os padrões são sintéticos, determinísticos, limitados, locais, apenas CPU, sem rede e dry-run onde o treinamento ocorreria de outra forma.

Instalação e proveniência

3.0.0 publicado

O PyPI fornece apenas pufferlib-3.0.0.tar.gz:

sha256: 7df3a3e3f5f894d78d2a1f5374097890aec01473183e748abefe4f3faa10eaa9
Requires-Python: >=3.9

Após a revisão do código-fonte/compilação, crie um projeto uv fixado:

uv venv --python 3.11
uv add --exact --no-sync "pufferlib==3.0.0"
uv lock
uv sync --frozen

Estes comandos de instalação são ilustrativos e não foram executados. Confirme pyproject.toml e uv.lock; verifique o digest do arquivo e cada dependência resolvida. A compilação do código-fonte pode compilar código nativo e buscar ativos de compilação, portanto, resolva/compile em um ambiente isolado sem credenciais ou montagens sensíveis. O arquivo declara NumPy <2, Gymnasium <=0.29.1 e PettingZoo <=1.24.1; o Gymnasium/NumPy mais recente não são substitutos válidos para este perfil. Sua configuração suporta Linux/macOS e rejeita outros sistemas. Os classificadores Python por si só não estabelecem uma compilação nativa bem-sucedida. Os metadados enviados não fixam Torch ou CUDA; não reivindique uma matriz CUDA suportada que o PyPI não declare.

Código-fonte 4.0 fixado

A cabeça do branch revisada em 2026-07-23 foi:

25647630e1b15330bb3153a5a0d3ff8d234c3acf

Fixe o commit, não o branch 4.0:

uv add --no-sync \
  "pufferlib @ git+https://github.com/PufferAI/PufferLib.git@25647630e1b15330bb3153a5a0d3ff8d234c3acf"
uv lock

O pacote 4.0 revisado declara Python >=3.10 e Torch >=2.9. O snapshot revisado do PufferTank usa Ubuntu 24.04, Python 3.12 e uma imagem de desenvolvimento NVIDIA CUDA 13.0.2/cuDNN com o índice Torch cu130, mas não fixa a roda exata do Torch ou todos os pacotes do sistema. Trate-o como uma referência, não como um

…