# andreped/super-ml-pets architecture

> Architecture diagram of the GitHub repository andreped/super-ml-pets, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andreped/super-ml-pets
- Repository: https://github.com/andreped/super-ml-pets

## Overview

##### 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/).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core smp package
    subgraph "smp package"
        direction TB
        Main["CLI Controller\nmain.py"]:::core
        Train["Training Module\ntrain_agent.py"]:::core
        Deploy["Deployment Module\ndeploy_agent.py"]:::core
        ImageDet["Image Detection\nimage_detection.py"]:::core
        Actions["Actions Submodule\nactions.py"]:::core
        Plot["Plotting Module\nplot_history.py"]:::core
        Utils["Utilities Module\nutils.py"]:::core
    end

    %% External systems and libraries
    Gym["Gym Env\n(sapai-gym)"]:::external
    RL["Stable-Baselines3\nRL Library"]:::external
    CV["OpenCV/PIL\nComputer Vision"]:::external
    InputLib["pynput/keyboard\nInput Control"]:::external
    Game["External Game\nProcess"]:::external
    ModelStore[(Model Storage\n& CSV Logs)]:::external
    Chart["Chart Output\n(image)"]:::external

    %% Utilities and assets
    Assets["Static Assets\nassets/"]:::dashed
    Tests["Test Suite\ntests/"]:::dashed

    %% CLI routing
    Main -->|"--task train"| Train
    Main -->|"--task deploy"| Deploy
    Main -->|"--task plot"| Plot

    %% Training pipeline
    Train -->|"env init"| Gym
    Train -->|"uses actions"| Actions
    Train -->|"trains with"| RL
    RL -->|"model checkpoints/logs"| ModelStore

    %% Deployment pipeline
    Deploy -->|"capture loop"| ImageDet
    ImageDet -->|"frames"| CV
    ImageDet -->|"state data"| Actions
    Actions -->|"action commands"| InputLib
    InputLib -->|"controls"| Game

    %% Plotting pipeline
    Plot -->|"reads CSV"| ModelStore
    Plot -->|"generates"| Chart

    %% Shared utilities
    Train --> Utils
    Deploy --> Utils
    Plot --> Utils

    %% Dashed boxes
    Utils --- Tests
    Main --- Assets

    %% Click events
    click Main "https://github.com/andreped/super-ml-pets/blob/main/main.py"
    click Train "https://github.com/andreped/super-ml-pets/blob/main/smp/train_agent.py"
    click Deploy "https://github.com/andreped/super-ml-pets/blob/main/smp/deploy_agent.py"
    click ImageDet "https://github.com/andreped/super-ml-pets/blob/main/smp/image_detection.py"
    click Actions "https://github.com/andreped/super-ml-pets/blob/main/smp/actions.py"
    click Plot "https://github.com/andreped/super-ml-pets/blob/main/smp/plot_history.py"
    click Utils "https://github.com/andreped/super-ml-pets/blob/main/smp/utils.py"
    click Assets "https://github.com/andreped/super-ml-pets/tree/main/assets/"
    click Tests "https://github.com/andreped/super-ml-pets/tree/main/tests/"

    %% Styles
    classDef core fill:#ccffcc,stroke:#009900,stroke-width:2px
    classDef external fill:#cce0ff,stroke:#0066cc,stroke-width:2px
    classDef dashed fill:#eeeeee,stroke:#666666,stroke-dasharray: 5 5,stroke-width:1px

    %% Legend
    subgraph Legend
        direction TB
        L1["Core Python Modules"]:::core
        L2["External Dependencies"]:::external
        L3["Assets & Tests"]:::dashed
    end
```
