# patil-ojas/street-fighter-ai architecture

> Architecture diagram of the GitHub repository patil-ojas/street-fighter-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/patil-ojas/street-fighter-ai
- Repository: https://github.com/patil-ojas/street-fighter-ai

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Assets
    roms["ROM Assets"]:::external
    roms_md["ROM Metadata"]:::external
    roms -->|"ROM load"| gym
    roms_md -.-> gym

    %% Training Infrastructure
    subgraph "Training Infrastructure"
        direction TB
        gym["Gym-Retro Environment"]:::external
        optuna["Optuna Controller"]:::compute
        loop["Training Loop"]:::compute
        agent["PPO Agent (SB3/PyTorch)"]:::compute
        tensorboard["TensorBoard Logs"]:::datastore
        modelstore["Model Store"]:::datastore

        optuna -->|"trial configs"| loop
        loop -->|"get action"| agent
        agent -->|"action"| gym
        gym -->|"observation"| loop
        gym -->|"reward"| loop
        loop -->|"metrics"| tensorboard
        loop -->|"save model"| modelstore
    end

    %% Notebooks (UI)
    notebook_demo["Demo Notebook"]:::ui
    notebook_test["Test Notebook"]:::ui

    notebook_demo -->|"load model"| modelstore
    notebook_demo -->|"visualize env"| gym
    notebook_test -->|"load model"| modelstore

    %% Project Files
    readme["README.md"]:::external
    license["LICENSE"]:::external
    deps["requirements.txt"]:::external

    %% Click Events
    click roms "https://github.com/patil-ojas/street-fighter-ai/tree/main/roms/"
    click roms_md "https://github.com/patil-ojas/street-fighter-ai/blob/main/roms/Street Fighter II' - Special Champion Edition (USA).md"
    click agent "https://github.com/patil-ojas/street-fighter-ai/blob/main/streetfighter.ipynb"
    click optuna "https://github.com/patil-ojas/street-fighter-ai/blob/main/streetfighter.ipynb"
    click tensorboard "https://github.com/patil-ojas/street-fighter-ai/tree/main/logs/"
    click modelstore "https://github.com/patil-ojas/street-fighter-ai/tree/main/test/"
    click notebook_demo "https://github.com/patil-ojas/street-fighter-ai/blob/main/streetfighter.ipynb"
    click notebook_test "https://github.com/patil-ojas/street-fighter-ai/blob/main/test/StreetFighter-Test.ipynb"
    click deps "https://github.com/patil-ojas/street-fighter-ai/blob/main/requirements.txt"
    click readme "https://github.com/patil-ojas/street-fighter-ai/blob/main/README.md"
    click license "https://github.com/patil-ojas/street-fighter-ai/tree/main/LICENSE"

    %% Styles
    classDef compute fill:#cfe2f3,stroke:#084b8a,stroke-width:1px
    classDef datastore fill:#d9ead3,stroke:#38761d,stroke-width:1px
    classDef external fill:#f9cb9c,stroke:#a64d14,stroke-width:1px
    classDef ui fill:#d9d2e9,stroke:#5b0f6e,stroke-width:1px
```
