DOCSEARCHbyAlgolia
Submit Docs

Generative Agents Research Framework

repository·main·Indexed 12 days ago

https://github.com/joonspk-research/generative_agents

A research framework for simulating believable human behaviors using large language models. It includes the Smallville environment and a simulation engine to manage agent interactions, memories, and social dynamics. The system requires Python 3.9.12 and utilizes a dual-server architecture consisting of an Environment Server (Django) and a Simulation Server (reverie.py).

Tokens
1.3K
Snippets
3
Records
5
Agent score
48%

What's inside Generative Agents

  1. Replay and Demo a simulation

    main

    Replaying a Simulation

    To view a previously saved simulation, ensure the environment server is running and visit: http://localhost:8000/replay/<simulation-name>/<starting-time-step>

    Demoing a Simulation

    Replays use identical character sprites. To see a proper demo with correct sprites, you must first compress the simulation using the compress_sim_storage.py script in the reverie directory.

    Once compressed, visit: http://localhost:8000/demo/<simulation-name>/<starting-time-step>/<simulation-speed>

    Parameters:

    • <simulation-name>: The name used when saving the simulation.
    • <starting-time-step>: The integer time-step to begin.
    • <simulation-speed>: An integer from 1 (slowest) to 5 (fastest).

  2. Run a new agent simulation

    main

    Running a simulation requires two concurrent servers: the Environment Server and the Simulation Server.

    1. Start the Environment Server

    1. Navigate to environment/frontend_server (where manage.py is located).
    2. Run the Django server:
      python manage.py runserver
    3. Verify by visiting http://localhost:8000/. You should see: "Your environment server is up and running."

    2. Start the Simulation Server

    1. Open a new terminal and navigate to reverie/backend_server.
    2. Run the simulation script:
      python reverie.py
    3. When prompted for the forked simulation, enter a base name (e.g., base_the_ville_isabella_maria_klaus for a 3-agent simulation).
    4. When prompted for the new simulation, enter a unique name for your current run (e.g., test-simulation).

    3. Execute Simulation Steps

    1. Open your browser to http://localhost:8000/simulator_home to view the map.
    2. In the simulation server terminal, use the run command followed by the number of steps:
      run <step-count>
      Note: 1 game step = 10 seconds. For 100 steps, use run 100.
    3. After steps complete, you can:
      • Run more steps: run <step-count>
      • Exit without saving: exit
      • Save and exit: fin
    # Start Environment Server
cd environment/frontend_server
python manage.py runserver

# Start Simulation Server
cd reverie/backend_server
python reverie.py

# Command inside Simulation Server
run 100

  3. Customize agent history and base simulations

    main

    Load Agent History

    To initialize agents with specific memories, you can load a CSV history file into a running simulation.

    1. Start a base simulation (e.g., base_the_ville_isabella_maria_klaus).
    2. At the Enter option: prompt, use the call command:
      call -- load history the_ville/<history_file_name>.csv
    3. Custom history files should be placed in: environment/frontend_server/static_dirs/assets/the_ville.

    Create New Base Simulations

    To create a custom base simulation, copy an existing base simulation folder and edit it. If you need to change agent names or increase the agent capacity of the Smallville map, you may need to edit the map files using the Tiled map editor.

    call -- load history the_ville/agent_history_init_n3.csv

  4. Set up the Generative Agents environment

    main

    To set up the simulation environment, you must generate a utils.py file and install dependencies.

    1. Generate utils.py

    Create a file named utils.py in the reverie/backend_server directory (the same folder containing reverie.py). Paste the following template and replace the placeholders with your OpenAI API key and name:

    # Copy and paste your OpenAI API Key
openai_api_key = "<Your OpenAI API>"
# Put your name
key_owner = "<Name>"

maze_assets_loc = "../../environment/frontend_server/static_dirs/assets"
env_matrix = f"{maze_assets_loc}/the_ville/matrix"
env_visuals = f"{maze_assets_loc}/the_ville/visuals"

fs_storage = "../../environment/frontend_server/storage"
fs_temp_storage = "../../environment/frontend_server/temp_storage"

collision_block_id = "32125"

# Verbose 
debug = True

    2. Install Dependencies

    Install the packages listed in requirements.txt. It is highly recommended to use a virtual environment. The environment was tested using Python 3.9.12.