How andreped/super-ml-pets works
Project Type and Purpose
• This is a specialized machine-learning framework (Python CLI tool) for training and deploying reinforcement-learning (RL) agents to play the game “Super Auto Pets.”
• It combines a simulated environment (via a gym wrapper) for training (train_agent.py) with a computer‐vision & control pipeline (image_detection.py + deploy_agent.py) for live deployment in the real game.
High-Level Components
A. Command-Line Interface (main.py)
• Parses arguments (--task train/deploy/plot).
• Routes to the appropriate sub-module (train_agent, deploy_agent, plot_history).
B. Training Pipeline (smp/train_agent.py & smp/actions.py)
• Gym-based environment integration (sapai-gym) for simulated game.
• RL algorithm (stable-baselines3 or similar) that uses actions.py to wrap environment actions.
• Model checkpointing and history logging (csv logs).
C. Deployment Pipeline (smp/deploy_agent.py, smp/image_detection.py, smp/actions.py)
• Image capture & analysis to extract board state from game screen (OpenCV or PIL).
• Model inference to decide next move.
• Input injection via keyboard/mouse events (pynput/keyboard) to control the game.
D. Utilities (smp/utils.py)
• Common helper functions (configuration parsing, file I/O, logging setup).
E. Plotting (smp/plot_history.py)
• Reads training CSV logs to generate training-history charts.
F. Tests (tests/)
• Unit tests for each smp module.
G. Assets (assets/)
• Static images used by documentation and possibly for screen-matching calibration.
External Dependencies & Technologies
• Python 3.7–3.11
• Reinforcement-learning library (e.g., stable-baselines3)
• Gym wrapper for Super Auto Pets (sapai-gym)
• Computer vision: OpenCV / PIL / numpy
• Input control: pynput or keyboard
• virtualenv for environment isolation
• GitHub Actions for CI (codeql, tests)
Relationships & Data Flow
• User runs main.py → CLI parser.
• If task=train:
· train_agent loads environment → actions.py defines possible moves → RL algorithm trains → snapshots written to disk + CSV log.
• If task=deploy:
· deploy_agent starts camera loop → image_detection captures game screen → board state fed into model → chosen action mapped to keyboard event via actions.py → repeat.
• If task=plot:
· plot_history reads CSV → generates chart image.
Architectural Patterns
• Modular structure: separate training vs. deployment concerns.
• Pipeline pattern for both training and deployment (sequence of small steps).
• CLI command dispatcher in main.py.
• Utility layer for shared code.
• Test-driven development (unit tests in tests/).