AscensionAI Scripts

Common Entry Points

Desktop control panel

Use this for most local runs. It launches workers, starts/stops training, tails logs, and recommends worker counts.

AscensionAI.pyw

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`

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 530-float vector with player, card, monster, 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