ppo-from-scratch

🇧🇷 Português | 🇺🇸 English

PPO (Proximal Policy Optimization, variante Clip) implementado do zero em PyTorch, com GAE e um estudo de ablation dos seus componentes.

Visão geral

Implementação on-policy e modular do PPO, em quatro unidades desacopladas: ActorCritic (rede), RolloutBuffer (armazenamento + GAE), PPO (objetivo clipado + update) e PPOTrainer (loop coleta-rollout → update). Inclui um estudo de ablation que mede o efeito de remover GAE, clipping e entropy bonus.

Arquitetura

• ActorCritic (ppo/networks.py) — tronco compartilhado, cabeça de política + valor.
• RolloutBuffer (ppo/rollout_buffer.py) — rollout on-policy; GAE/retornos; minibatches. Flag use_gae.
• PPO (ppo/ppo.py) — act, update (objetivo PPO-clip). Flags use_clipping, use_entropy.
• PPOTrainer (ppo/trainer.py) — loop on-policy + métricas (History).

As três flags de ablation vivem num único PPO/buffer configurável — sem código duplicado.

Instalação (uv)

uv sync --extra dev

Como usar

import gymnasium as gym
from ppo import PPO, RolloutBuffer, PPOTrainer

env = gym.make("CartPole-v1")
obs_dim = env.observation_space.shape[0]; n = env.action_space.n
agent = PPO(obs_dim, n)
buf = RolloutBuffer(size=2048, obs_dim=obs_dim)
trainer = PPOTrainer(agent, env, buf, seed=0)
hist = trainer.train(total_steps=100_000, rollout_len=2048)
print(trainer.evaluate(num_episodes=10))

Experimentos

uv run python experiments/run_cartpole.py      # validação (PPO atinge ~414/500)
uv run python experiments/run_lunarlander.py   # PPO completo
uv run python experiments/run_ablation.py      # ablation (GAE/clip/entropy)

Resultados em results/. Documentação: docs/ — incluindo o estudo de ablation, onde remover o GAE se mostrou o mais prejudicial.

Testes

uv run pytest

Inclui testes numéricos exatos do GAE e do objetivo clipado.

Licença

MIT — ver LICENSE.