# humancompatibleai/overcooked_ai architecture

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

- Interactive diagram: https://gitdiagram.com/humancompatibleai/overcooked_ai
- Repository: https://github.com/humancompatibleai/overcooked_ai

## Overview

##### Project Type & Purpose
- The project is a research benchmark environment aimed at studying cooperative human-AI interaction in a simulated Overcooked kitchen task. It mixes environment simulation (the MDP), planning and agent logic, some training infrastructure (deprecated human_aware_rl modules), and a demo web server to interact with trained agents.
- The README and file structure indicate multiple “layers” of the project: a simulation core, planning/agent modules, demo web server, and auxiliary tools (data processing, tests, and experiment-running scripts).

##### Main Components
A. Simulation & Core Environment (overcooked_ai_py)
- The mdp submodule (overcooked_mdp.py, overcooked_env.py, layout_generator.py) is the heart of the environment and game logic.
- The agents folder, including agent implementations and benchmarking utilities, form the decision-making and evaluation layer.
- The planning folder (planners.py, search.py) provides near-optimal planning and search logic used to back the agent strategies.
- Visualization utilities (under visualization/) that support state rendering and possibly debugging the simulation.

B. Demo Server & UI (overcooked_demo)
- A Flask server (app.py, game.py) that serves as the interactive front-end.
- Static assets (JavaScript, CSS, images, templates) required for the web presentation of the game.
- Integration scripts such as move_agents.py and docker-compose/up.sh that aid deployment.

C. Training & Data Processing (human_aware_rl)
- Although now deprecated, this module contains parts for behavior cloning and PPO training. It’s organized into:
- PPO-related code with training, evaluation, and experiment scripts.
- Imitation learning for behavior cloning.
- Data processing utilities for human gameplay data.
- The static folder also includes datasets like “human_data” and testing datasets which serve as training and benchmarks.

D. Supporting Scripts & Tests
- Testing scripts in the “testing” folder and continuous integration configurations (.github, codecov, pyproject.toml, etc.) which ensure the reliability of all modules.
- Setup and installation files (setup.py, pyproject.toml) which provide dependency management and configuration.

##### Relationships & Data Flow
- The core simulation (mdp) underpins both the planning/agent modules and the demo server; it is effectively shared between training agents and real-time gameplay.
- The planning logic uses the simulation core to compute trajectories and strategies (data flow from simulation → planning → agents).
- Although deprecated, the human_aware_rl module shows the training loop for reinforcement learning and imitation—which involves a cyclical data flow: Raw Human Data (from static/Human Data) → Data Processing → Training (PPO / BC) → Trained Agent exported to the demo.
- Continuous Integration (CI) components and utilities enable testing flow throughout the system.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Distinct packages separating simulation (mdp), decision-making (agents/planning), user interface (demo server), and experimental/training work (human_aware_rl).
- Modular Design: Each component is a self-contained package with dedicated responsibilities (e.g., layout generation vs. agent benchmarking).
- Integration via APIs: The demo server (Flask app) calls the simulation and agent modules as libraries. Also, planned compatibility via rllib wrappers further modularizes training interfaces.
- Extensibility: New layouts, agents, or training algorithms can be incorporated primarily by adding new modules or updating existing ones.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Simulation & Core Environment
    subgraph "Simulation & Core Environment"
        subgraph "MDP Core"
            MDP1["overcooked_mdp.py"]:::core
            MDP2["overcooked_env.py"]:::core
            MDP3["layout_generator.py"]:::core
        end
        AM["Agents Module"]:::core
        PL["Planning Layer"]:::core
        VIZ["Visualization Utilities"]:::core
    end

    %% Demo Server & UI
    subgraph "Demo Server & UI"
        subgraph "Backend"
            APP["app.py"]:::demo
            GAME["game.py"]:::demo
        end
        DS["Deployment Scripts"]:::demo
        STATIC["Static Assets"]:::demo
    end

    %% Training & Data Processing (Deprecated)
    subgraph "Training & Data Processing"
        PPO["PPO Training"]:::train
        Imit["Imitation Learning"]:::train
        DPU["Data Processing Utilities"]:::train
        DATA["Static Datasets"]:::train
    end

    %% Supporting Scripts & Tests
    subgraph "Supporting Scripts & Tests"
        TEST["Testing Scripts"]:::support
        CICD["CI/CD & Configurations"]:::support
    end

    %% Relationships within Simulation & Core Environment
    MDP1 -->|"uses"| PL
    PL -->|"guides"| AM

    %% Demo Server interactions with Simulation components
    APP -->|"calls"| MDP1
    APP -->|"calls"| AM

    %% Training data processing flow
    DATA -->|"feeds"| DPU
    DPU -->|"triggers"| PPO
    DPU -->|"triggers"| Imit
    PPO -->|"exportsAgent"| APP
    Imit -->|"exportsAgent"| APP

    %% CI/CD integration with testing
    CICD -->|"validates"| TEST

    %% Click Events for Simulation & Core Environment
    click MDP1 "https://github.com/humancompatibleai/overcooked_ai/blob/master/src/overcooked_ai_py/mdp/overcooked_mdp.py"
    click MDP2 "https://github.com/humancompatibleai/overcooked_ai/blob/master/src/overcooked_ai_py/mdp/overcooked_env.py"
    click MDP3 "https://github.com/humancompatibleai/overcooked_ai/blob/master/src/overcooked_ai_py/mdp/layout_generator.py"
    click AM "https://github.com/humancompatibleai/overcooked_ai/tree/master/src/overcooked_ai_py/agents"
    click PL "https://github.com/humancompatibleai/overcooked_ai/tree/master/src/overcooked_ai_py/planning"
    click VIZ "https://github.com/humancompatibleai/overcooked_ai/tree/master/src/overcooked_ai_py/visualization"

    %% Click Events for Demo Server & UI
    click APP "https://github.com/humancompatibleai/overcooked_ai/blob/master/src/overcooked_demo/server/app.py"
    click GAME "https://github.com/humancompatibleai/overcooked_ai/blob/master/src/overcooked_demo/server/game.py"
    click DS "https://github.com/humancompatibleai/overcooked_ai/blob/master/src/overcooked_demo/docker-compose.yml"
    click STATIC "https://github.com/humancompatibleai/overcooked_ai/tree/master/src/overcooked_demo/server/static"

    %% Click Events for Training & Data Processing
    click PPO "https://github.com/humancompatibleai/overcooked_ai/tree/master/src/human_aware_rl/ppo"
    click Imit "https://github.com/humancompatibleai/overcooked_ai/tree/master/src/human_aware_rl/imitation"
    click DPU "https://github.com/humancompatibleai/overcooked_ai/tree/master/src/human_aware_rl/human"
    click DATA "https://github.com/humancompatibleai/overcooked_ai/tree/master/src/human_aware_rl/static/human_data"

    %% Click Events for Supporting Scripts & Tests
    click TEST "https://github.com/humancompatibleai/overcooked_ai/tree/master/testing"
    click CICD "https://github.com/humancompatibleai/overcooked_ai/blob/master/.github"

    %% Styles
    classDef core fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef demo fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef train fill:#cce5ff,stroke:#004085,stroke-width:2px,stroke-dasharray: 5 5;
    classDef support fill:#fff5cc,stroke:#996600,stroke-width:2px;
```
