How patil-ojas/street-fighter-ai works
Project Type and Purpose
• This is an open-source AI/ML tool that teaches a reinforcement-learning (RL) agent (via Stable-Baselines3’s PPO) to play Street Fighter II inside an OpenAI-Gym/RL Retro environment.
• The README and file tree confirm key elements: ROM assets, training logs, notebooks for demo and testing, and dependencies for PyTorch, Gym, PPO, SB3, and Optuna.
File Structure Analysis
• Top-level:
• README.md, LICENSE, requirements.txt
• logs/ (TensorBoard event logs for multiple PPO runs)
• roms/ (game ROM files and metadata)
• streetfighter.ipynb (demo & interactive training/inference)
• test/ (test notebook + pre-trained model archives)
• No web frontend or microservices—this is a single Python application orchestrating RL training and evaluation.
Key Components
a. ROM & Emulator Layer
• “roms/” provides the game binary.
• Wrapped by the Gym-Retro/OpenAI Gym environment (“gym-retro” or custom env class).
b. RL Agent & Training
• Stable-Baselines3 PPO agent (PyTorch under the hood).
• Training loop: agent ↔ environment interaction (observations → actions → rewards).
c. Hyperparameter Optimization
• Optuna orchestrates multiple training trials with different PPO hyperparameters.
• Each trial’s metrics feed into Optuna’s study.
d. Logging & Monitoring
• TensorBoard writer captures episode rewards, losses, learning rate, etc.
• Logs saved under logs/PPO_X/events.out.tfevents…
e. Model Storage & Artifacts
• Trained models serialized as .zip in test/ and user-specified model directory.
• ROM metadata .md files for clarity.
f. Interactive Notebooks
• streetfighter.ipynb: for demo visualization and manual inference.
• test/StreetFighter-Test.ipynb: for validating agent performance against saved models.
Relationships and Data Flows
• The Gym-Retro env loads the ROM → produces state observations → passed to the PPO agent → agent outputs actions → env steps forward → yields next observations & rewards → loop continues.
• During each episode:
• Training loop pushes metrics to TensorBoard.
• Optuna intercepts training runs to tune hyperparameters.
• When training completes (end of trial or target timesteps), agent model is saved (.zip).
• Notebooks load saved models for inference / visualization by querying the environment.
Architectural Patterns & Design Principles
• Modularity: clear separation between environment (game emulator) and agent logic.
• Experimentation scaffold: logs + hyperparameter tuning externalize configuration from core training code.
• Extensibility: users can swap in different algorithms (e.g., DQN, A2C) by adjusting the SB3 agent component.