Agents RL (A.N.N.A)

Esta carpeta contiene scripts reproducibles para entrenar y evaluar un agente RL en core_v2/tests/TestScene_RL.tscn.

Escena alternativa más difícil:

• core_v2/tests/TestScene_RL_2.tscn (obstáculos/corredores/pilares)
• core_v2/tests/TestScene_RL_3.tscn (laberinto + vallas bajas para salto/corrección)
• core_v2/tests/TestScene_RL_BaseTerrace.tscn (wrapper RL que instancia core_v2/levels/BaseTerrace.tscn real)

Requisitos

• Python 3
• gymnasium
• stable-baselines3
• Godot 3.6 (godot3-bin) o GODOT_BIN configurado

Ejemplo:

pip install gymnasium stable-baselines3

Run recomendado (overnight)

Si quieres un run largo, ordenado por carpeta y con pre-check de FPS:

./agents/run_overnight_best.sh

Runbook operativo:

• agents/RUNBOOK_OVERNIGHT.md

Regla critica de rendimiento:

• No usar ANNA_GODOT_MAX_FPS=0 con godot3-server (baja mucho los SPS).

1) Entrenar modelo

Headless (recomendado):

python3 agents/train_anna.py --timesteps 200000 --cpu-threads 4

Entrenar en nivel difícil:

python3 agents/train_anna.py --scene core_v2/tests/TestScene_RL_2.tscn --timesteps 200000 --cpu-threads 4

Curriculum (nivel 1 -> nivel 2):

python3 agents/train_anna_curriculum.py \
  --scene-stage1 core_v2/tests/TestScene_RL.tscn \
  --scene-stage2 core_v2/tests/TestScene_RL_2.tscn \
  --timesteps-stage1 16000 \
  --timesteps-stage2 16000 \
  --cpu-threads 6

Curriculum pedido (8k fácil + resto nivel 2):

python3 agents/train_anna_curriculum.py \
  --scene-stage1 core_v2/tests/TestScene_RL.tscn \
  --scene-stage2 core_v2/tests/TestScene_RL_2.tscn \
  --timesteps-stage1 8000 \
  --timesteps-stage2 16000 \
  --cpu-threads 6 \
  --model-out agents/models/anna_ppo_lvl1_8k_lvl2_16k_v1.zip

Curriculum de 3 niveles (incluye nivel 3):

python3 agents/train_anna_curriculum.py \
  --scene-stage1 core_v2/tests/TestScene_RL.tscn \
  --scene-stage2 core_v2/tests/TestScene_RL_2.tscn \
  --scene-stage3 core_v2/tests/TestScene_RL_BaseTerrace.tscn \
  --timesteps-stage1 8000 \
  --timesteps-stage2 8000 \
  --timesteps-stage3 8000 \
  --cpu-threads 6 \
  --model-out agents/models/anna_ppo_lvl1_lvl2_lvl3_24k_v1.zip

Con ventana (para observar):

python3 agents/train_anna.py --timesteps 50000 --render --cpu-threads 4

Entrenamiento grande en GPU CUDA (curriculum RL -> RL_2 -> BaseTerrace wrapper):

./agents/run_train_best_cuda.sh

No requiere .venv en servidor: si existe lo activa automáticamente; si no, usa el Python activo del sistema.

El script grande aplica por defecto el equivalente a:

__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia python agents/train_anna_cuda_big.py

Puedes personalizar sin editar el script, por ejemplo:

CPU_THREADS=12 \
NUM_ENVS=8 \
CUDA_VISIBLE_DEVICES=0 \
STAGE1_STEPS=150000 \
STAGE2_STEPS=650000 \
STAGE3_STEPS=700000 \
MODEL_OUT=agents/models/anna_ppo_cuda_big_custom.zip \
./agents/run_train_best_cuda.sh

Preset robusto para Vast.ai (sin .venv, más tolerancia de arranque):

PYTHON_BIN=python \
CPU_THREADS=16 \
NUM_ENVS=8 \
ANNA_GODOT_PREFER_SERVER=1 \
ANNA_GODOT_SERVER_FALLBACK=1 \
ANNA_GODOT_READY_TIMEOUT_SEC=90 \
ANNA_CONNECT_MAX_RETRIES=90 \
./agents/run_train_best_cuda.sh

Antes de entrenar, run_train_best_cuda.sh corre un paso estilo GitHub Actions:

• import global de recursos (godot -e --headless)
• smoke de recursos críticos (tests/ci_resource_smoke.gd)
• retry automático de smoke una vez

Logs:

• reports/import_resources_train.log
• reports/resource_smoke_train.log
• reports/resource_smoke_train_retry.log

Control por env:

• ANNA_PREIMPORT_BEFORE_TRAIN=0 desactiva el paso
• ANNA_PREIMPORT_REQUIRED=0 permite continuar aunque falle
• ANNA_IMPORT_FORCE_SOFTWARE=1 fuerza LIBGL_ALWAYS_SOFTWARE=1 (default)
• ANNA_PREIMPORT_DISABLE_EDITOR_PLUGINS=1 desactiva temporalmente plugins en el pass de import (default)
• ANNA_IMPORT_GODOT_BIN=godot3 fija binario de import/smoke (si GODOT_BIN=godot3-server, el launcher ya evita usar server para preimport)
• ANNA_SKIP_PY_PREWARM_AFTER_PREIMPORT=1 evita duplicar prewarm en Python (default)

Notas de throughput por defecto del launcher CUDA:

• ANNA_RL_PHYSICS_FPS=0 (preset uncapped de AnnaBridge)
• ODISEA_DISABLE_PERFMON_IN_RL=1 (evita overhead del monitor en entrenamiento)
• ODISEA_DISABLE_FAKE_SHADOW=1 (desactiva blob/fake shadow del piloto en RL)
• ODISEA_DISABLE_SHADER_WARMUP=1 (evita compilación de shader cache runtime en RL)
• ANNA_RL_DISABLE_QODOT=1 (desactiva comportamiento de Qodot en wrapper RL BaseTerrace)
• BATCH_SIZE=8192
• NUM_ENVS_STAGE3=2 por defecto para estabilizar BaseTerrace (stage3)
• ANNA_CUDA_TF32=1, ANNA_CUDNN_BENCHMARK=1, ANNA_TORCH_MATMUL_PRECISION=high

Script base (si prefieres invocarlo directo):

python3 agents/train_anna_cuda_big.py --device auto --model-out agents/models/anna_ppo_cuda_big.zip

Salida por defecto:

• Modelo: agents/models/anna_ppo.zip
• Metadata: agents/models/anna_ppo.meta.json

2) Evaluar / ver el agente

python3 agents/eval_anna.py --model agents/models/anna_ppo.zip --episodes 5 --render --cpu-threads 4

3) Arnés autónomo (train/eval hasta mejorar dirección)

Este script itera rondas entrenar -> evaluar -> puntuar y guarda:

• checkpoints por ronda: agents/models/anna_auto_rN.zip
• mejor modelo acumulado: agents/models/anna_auto_best.zip
• resumen completo: agents/models/anna_auto_summary.json

Ejemplo:

python3 agents/auto_train_anna.py \
  --cpu-threads 6 \
  --rounds 1 \
  --scene-stage1 core_v2/tests/TestScene_RL.tscn \
  --scene-stage2 core_v2/tests/TestScene_RL_2.tscn \
  --scene-stage3 core_v2/tests/TestScene_RL_BaseTerrace.tscn \
  --timesteps-stage1 8000 \
  --timesteps-stage2 16000 \
  --timesteps-stage3 8000 \
  --eval-episodes 6 \
  --eval-max-steps 800 \
  --success-target 0.5 \
  --direction-target 0.62 \
  --fast-success-target 0.45 \
  --wall-contact-max 0.18

Limitar CPU (evitar sobrecalentamiento)

Ambos scripts aplican límite de hilos vía --cpu-threads:

• OMP_NUM_THREADS
• MKL_NUM_THREADS
• OPENBLAS_NUM_THREADS
• NUMEXPR_NUM_THREADS
• torch.set_num_threads()

Si quieres limitar aún más, en Linux puedes combinarlos con taskset.

Notas

• En modo RL (ANNA_RL_MODE=1) el mundo avanza en lock-step (un STEP -> un frame físico).
• Convención del proyecto: -Z es forward y +Z es back.