Desktop control panel
Use this for most local runs. It launches workers, starts/stops training, tails logs, and recommends worker counts.
AscensionAI.pyw
Common Entry Points
PowerShell launcher
Use this when you want terminal-first launch control over workers, BC, PPO, evaluation, or passive logging.
launch_workers.ps1
Static dashboard
Use this to inspect public snapshot metrics or load fresh local CSV files from logs/.
docs/dashboard/index.html
Training and Collection Scripts
| File | Role | Use When | Typical Command |
|---|---|---|---|
scripts/train_bc_ppo.py |
end-to-end | Runs behavior cloning first, then PPO fine-tuning in one Communication Mod session. | python scripts/train_bc_ppo.py --bc-games 150 --ppo-games 200 |
scripts/behavior_clone.py |
BC warm start | Collects heuristic demonstrations and trains the PPO network with supervised cross-entropy. | python scripts/behavior_clone.py --games 150 --save models/ppo_sts_bc.pt |
scripts/train_ppo.py |
single worker PPO | Trains PPO from one live game instance without the parallel rollout queue. | python scripts/train_ppo.py --save models/ppo_sts.pt --resume models/ppo_sts.pt |
scripts/rollout_worker.py |
collector | Runs inside each Slay the Spire instance and writes per-game rollout files to a shared directory. | python scripts/rollout_worker.py --model models/ppo_sts.pt --out rollouts_shared --id 1 |
scripts/train_offline.py |
central trainer | Consumes batches of worker rollout files, rejects stale data, applies PPO updates, and saves the shared checkpoint. | python scripts/train_offline.py --model models/ppo_sts.pt --data rollouts_shared --delete-consumed |
Cloud / Headless Deployment (vm/)
| File | Role | Use When | Typical Command |
|---|---|---|---|
vm/install.sh |
one-shot installer | Provisions a fresh Ubuntu 22.04 VM: Java 8, Xvfb, OpenAL, Python venv + CPU torch, directory layout, and validation. Idempotent. | bash vm/install.sh |
vm/run_training.sh |
headless launcher | Launches N headless STS workers + the offline trainer; per-worker Xvfb display and JVM tmpdir, 2 GB heap, restart every 25 games, per-worker watchdog, lr override for new obs inputs. | ./vm/run_training.sh --workers 8 --hours 24 |
vm/monitor.sh |
self-healing cron | Runs from cron every 10 min: writes an auditable heartbeat and continuously relaunches training (while logs/.autorun is set) after any death, clean end, or reboot — session-independent. |
*/10 * * * * vm/monitor.sh |
vm/collect_bc.sh |
BC anchor demos | Headless heuristic demo collector (no net training) — gathers fresh 717-d demos into bc_demos_shared/ for the PPO BC anchor. |
./vm/collect_bc.sh --workers 4 --minutes 30 |
vm/run_eval.sh |
headless eval | Runs a fixed-seed evaluation headless (single or multi-instance), 8 GB heap to survive a full 200-game run. | ./vm/run_eval.sh --games 200 --instances 4 |
vm/sync.ps1 / vm/sync.sh |
sync | Push code/model/seeds to the VM and pull the model + logs back, via gcloud (PowerShell) or rsync (bash). | .\vm\sync.ps1 push · .\vm\sync.ps1 pull |
vm/quickstart.sh / vm/stop.sh |
ops | Printable cheat-sheet (VM creation, spot preemption recovery, cost) and a graceful stop with orphan-process sweep. | ./vm/quickstart.sh · ./vm/stop.sh |
Evaluation, Logging, and Analysis
| File | Role | Use When | Output |
|---|---|---|---|
scripts/eval_model.py |
greedy eval | Runs heuristic or model policies without exploration on fixed seeds. | logs/eval_stats.csv, logs/eval_debug.log |
scripts/make_eval_seeds.py |
seed generation | Creates deterministic seed lists for controlled comparisons. | seeds/eval_200.txt |
scripts/plot_training.py |
plotting | Draws floor, reward, win-rate, entropy, KL, clip, policy-loss, and value-loss curves. | logs/training_plot.png when run with --save |
scripts/analyze_training_rewards.py |
reward audit | Checks whether shaped reward correlates with actual progress metrics. | Terminal correlation report |
scripts/game_logger.py |
passive recorder | Records game states while a human plays manually, without sending gameplay actions. | logs/game_trace_*.jsonl |
scripts/analyze_trace.py |
trace summary | Summarizes passive trace files by screen type, room phase, flags, and sample choices. | Terminal screen-state report |
Environment and Model Modules
| File | Role | What It Contains |
|---|---|---|
scripts/obs_encoder.py |
observation encoder | Converts SpireComm game state into a fixed 585-float vector with player, card, monster (19 power slots), relic, potion, deck, screen, and map features. |
scripts/sts_gym_env.py |
environment | Defines the 134-action space, action masks, reward shaping, Gymnasium-style wrapper, and live Communication Mod interaction. |
scripts/ppo_model.py |
PPO core | Import-safe PPOTrainer and GameBuffer classes used by BC, PPO, workers, and offline training. |
scripts/screen_handler.py |
screen plumbing | Shared handling for non-combat screens, recovery paths, reward screens, map choices, shops, events, and grid selection. |
scripts/game_data.py |
game knowledge | Ironclad-relevant card, relic, and potion databases used by the observation encoder and heuristics. |
Stats and Shared Helpers
| File | Role | What It Standardizes |
|---|---|---|
scripts/training_stats_schema.py |
CSV schema | Shared training_stats.csv columns for training scripts and migration behavior when headers change. |
scripts/bc_stats.py |
BC logging | Per-game behavior-cloning metrics written to logs/bc_stats.csv. |
scripts/fight_tracker.py |
combat metrics | Elite and boss fight tracking, including terminal deaths that still report as in-combat. |
Typical Workflows
Fixed-seed comparison
python scripts\make_eval_seeds.py --count 200 --out seeds\eval_200.txt python scripts\eval_model.py --policy heuristic --games 200 --seed-file seeds\eval_200.txt python scripts\eval_model.py --model models\ppo_sts_bc.pt --games 200 --seed-file seeds\eval_200.txt python scripts\eval_model.py --model models\ppo_sts.pt --games 200 --seed-file seeds\eval_200.txt
Parallel PPO loop
.\launch_workers.ps1 -NumWorkers 3 python scripts\train_offline.py --model models\ppo_sts.pt --data rollouts_shared --delete-consumed --batch-games 8 --ent-coef 0.001 --auto-tune