# mkturkcan/generative-agents architecture

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

- Interactive diagram: https://gitdiagram.com/mkturkcan/generative-agents
- Repository: https://github.com/mkturkcan/generative-agents

## Overview

##### Main Components
- Core Simulation Module (game_simulation):
- Main Execution Flow: Represented by game_simulation/main.py, it orchestrates the simulation.
- Agents Subsystem: Under game_simulation/agents, this module (agent.py) encapsulates individual agent behaviors and attributes.
- Locations Subsystem: Located in game_simulation/locations, it details location-based functionalities, environment setup, or town mapping.
- Utility Functions: In game_simulation/utils (e.g., text_generation.py) which support text-based interactions and other helper functions.
- Configuration/Log Files: simulation_config.json defines parameters and simulation_log.txt records simulation events.
- Environment Template: .env.template provides environment variables needed for deployment or local setups.

- Demonstration and Experimentation (notebook):
- Released Notebook(s): Located under notebook/Release demonstrate stable and supported models.
- WIP Notebooks: Under notebook/WIP, these notebooks show evolving features and experimental setups for the simulation.

##### Relationships and Interactions
- The main simulation script (main.py) is at the center, initiating and coordinating the simulation by loading configurations, logging interactions, and invoking agent and location functionalities.
- The Agents Module interacts with the Locations Module to determine where simulation events take place. Agents might reference locations indirectly (e.g., through positions or events).
- The Utils module supports both agents and locations by providing text generation capabilities, likely generating dialogues or descriptions as the simulation advances.
- The configuration file (simulation_config.json) and logs (simulation_log.txt) are used by the main module to control run parameters and store outputs.
- Notebooks serve as interactive front-end demos or experiments, often calling into the same simulation libraries and may interface with the code in game_simulation for visualization and analysis.

##### Architectural Patterns and Key Technologies
- Modularity: The design separates agents, locations, and utilities into distinct modules, reflecting a modular design.
- Configuration Driven: With external JSON configuration and environment templates, the system supports flexible parameterization.
- Simulation Loop: The game simulation likely follows a main loop that integrates the decisions and actions of multiple agents over time.
- Notebook Integration: By providing separate notebooks for release and work-in-progress, the project emphasizes an iterative, experimental approach in presenting generative behavior simulations.

##### Final Advice
- Don’t overcomplicate—break the system down into as many key components as possible to capture all essential behaviors.
- Verify that every component mentioned in the file tree and documented in the README is represented.
- Assumptions (like the simulation loop or potential interactions not explicitly outlined in the code) for clarity.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Simulation Subgraph
    subgraph "Core Simulation"
        mainEngine["Main Simulation Engine (game_simulation/main.py)"]:::core
        subgraph "Modules"
            agents["Agents Module (game_simulation/agents): agent.py"]:::core
            locations["Locations Module (game_simulation/locations): locations.py"]:::core
            utils["Utilities (game_simulation/utils): text_generation.py"]:::support
        end
        subgraph "Configuration & Logging"
            config["Configuration File (simulation_config.json)"]:::support
            log["Logging File (simulation_log.txt)"]:::support
            env["Environment Template (.env.template)"]:::support
        end
    end

    %% Demonstration Notebooks Subgraph
    subgraph "Demonstration Notebooks"
        notebookRelease["Released Notebook (notebook/Release/generative_model_simple.ipynb)"]:::notebook
        notebookWIP["WIP Notebook (notebook/WIP/demo_01_phandalin_simulation.ipynb)"]:::notebook
    end

    %% Connections
    mainEngine -->|"invokes"| agents
    mainEngine -->|"invokes"| locations
    mainEngine -->|"calls"| utils
    agents -->|"interacts_with"| locations
    mainEngine -->|"loads"| config
    mainEngine -->|"writes_to"| log
    mainEngine -->|"reads"| env
    notebookRelease -->|"interfaces_with"| mainEngine
    notebookWIP -->|"interfaces_with"| mainEngine

    %% Styles
    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef support fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef notebook fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;

    %% Click Events
    click mainEngine "https://github.com/mkturkcan/generative-agents/blob/main/game_simulation/main.py"
    click agents "https://github.com/mkturkcan/generative-agents/blob/main/game_simulation/agents/agent.py"
    click locations "https://github.com/mkturkcan/generative-agents/blob/main/game_simulation/locations/locations.py"
    click utils "https://github.com/mkturkcan/generative-agents/blob/main/game_simulation/utils/text_generation.py"
    click config "https://github.com/mkturkcan/generative-agents/blob/main/game_simulation/simulation_config.json"
    click log "https://github.com/mkturkcan/generative-agents/blob/main/game_simulation/simulation_log.txt"
    click env "https://github.com/mkturkcan/generative-agents/blob/main/game_simulation/.env.template"
    click notebookRelease "https://github.com/mkturkcan/generative-agents/blob/main/notebook/Release/generative_model_simple.ipynb"
    click notebookWIP "https://github.com/mkturkcan/generative-agents/blob/main/notebook/WIP/demo_01_phandalin_simulation.ipynb"
```
