README added

xiaogang12 · Jul 29, 2023 · 51072d4 · 51072d4
1 parent 7ad910c
commit 51072d4
Show file tree

Hide file tree

Showing 16,941 changed files with 476,417 additions and 46 deletions.
diff --git a/README.md b/README.md
@@ -1,13 +1,16 @@
 
-# Generative Agents
-## Introduction 
-Generative Agents: Interactive Simulacra of Human Behavior
-This is the core simulation module for generative agents 
 
-## Setup 
-download everything in the requirements  
+# Generative Agents: Interactive Simulacra of Human Behavior 
 
-utils.py
+This repository accompanies our research paper titled "[Generative Agents: Interactive Simulacra of Human Behavior](https://arxiv.org/abs/2304.03442)." It contains our implementation of generative agents—computational agents that simulate believable human behaviors—and their simulated game environment. Below, we document the steps for setting up the simulation environment on your local machine and for replaying the simulation as a demo animation.
+
+*Usage Notice: This code repository of generative agents is intended for research use only.* 
+
+## Setting Up the Environment 
+To set up your environment, you will need to generate a `utils.py` file that contains your OpenAI API key and download the necessary packages.
+
+### Step 1. Generate Utils File
+In the `reverie/backend_server` folder (where `reverie.py` is located), create a new file titled `utils.py` and copy and paste the content below into the file:
 ```
 # Copy and paste your OpenAI API Key
 openai_api_key = "<Your OpenAI API>"
@@ -26,34 +29,74 @@ collision_block_id = "32125"
 # Verbose 
 debug = True
 ```
+Replace `<Your OpenAI API>` with your OpenAI API key, and `<name>` with your name.
+
+### Step 2. Install requirements.txt
+Install everything listed in the `requirements.txt` file (I strongly recommend first setting up a virtualenv as usual).
+
+## Running a Simulation 
+To run a new simulation, you will need to concurrently start two servers: the environment server and the agent simulation server.
+
+### Step 1. Starting the Environment Server
+Again, the environment is implemented as a Django project, and as such, you will need to start the Django server. To do this, first navigate to `environment/frontend_server` (this is where `manage.py` is located) in your command line. Then run the following command:
+
+    python manage.py runserver
+
+Then, on your favorite browser, go to [http://localhost:8000/](http://localhost:8000/). If you see a message that says, "Your environment server is up and running," your server is running properly. Ensure that the environment server continues to run while you are running the simulation, so keep this command-line tab open! (Note: I recommend using either Chrome or Safari. Firefox might produce some frontend glitches, although it should not interfere with the actual simulation.)
+
+### Step 2. Starting the Simulation Server
+Open up another command line (the one you used in Step 1 should still be running the environment server, so leave that as it is). Navigate to `reverie/backend_server` and run `reverie.py`.
 
+    python reverie.py
+This will start the simulation server. A command-line prompt will appear, asking the following: "Enter the name of the forked simulation: ". To start a 3-agent simulation with Isabella Rodriguez, Maria Lopez, and Klaus Mueller, type the following:
+
+    base_the_ville_isabella_maria_klaus
+The prompt will then ask, "Enter the name of the new simulation: ". Type any name to denote your current simulation (e.g., just "test-simulation" will do for now).
 
-## How to run a new simulation 
-start your django server 
+    test-simulation
+Keep the simulator server running. At this stage, it will display the following prompt: "Enter option: "
 
-- python manage.py runserver
-- travel to http://localhost:8000/simulator_home
-	- This has your simulation frontend running. This always have to be running
+### Step 3. Running and Saving the Simulation
+On your browser, navigate to [http://localhost:8000/simulator_home](http://localhost:8000/simulator_home). You should see the map of Smallville, along with a list of active agents on the map. You can move around the map using your keyboard arrows. Please keep this tab open. To run the simulation, type the following command in your simulation server in response to the prompt, "Enter option":
 
-open reverie.py 
-rs = ReverieServer("July1_the_ville_isabella_maria_klaus-step-3-11", 
-                     "July1_the_ville_isabella_maria_klaus-step-3-12") 
-you need to input sim_code there... 
-they should match the folder names in the storage file 
-if you are creating a new sim, the latter is the target location, the former is the source sim
+    run <step-count>
+Note that you will want to replace `<step-count>` above with an integer indicating the number of game steps you want to simulate. For instance, if you want to simulate 100 game steps, you should input `run 100`. One game step represents 10 seconds in the game.
 
-initialize memory via whisper
 
-save. 
-python reverie.py 
-run < step count>
+Your simulation should be running, and you will see the agents moving on the map in your browser. Once the simulation finishes running, the "Enter option" prompt will re-appear. At this point, you can simulate more steps by re-entering the run command with your desired game steps, exit the simulation without saving by typing `exit`, or save and exit by typing `fin`.
 
-save the simulation by typing fin... 
-I suggest saving because sometimes a prompt fails, or OpenAI hangs... 
+The saved simulation can be accessed the next time you run the simulation server by providing the name of your simulation as the forked simulation. This will allow you to restart your simulation from the point where you left off.
 
-## How to quickly replay a simulation (in testing) 
-http://localhost:8000/replay/July1_the_ville_isabella_maria_klaus-step-2-7/1/
+### Step 4. Replaying a Simulation
+You can replay a simulation that you have already run simply by having your environment server running and navigating to the following address in your browser: `http://localhost:8000/replay/<simulation-name>/<starting-time-step>`. Please make sure to replace `<simulation-name>` with the name of the simulation you want to replay, and `<starting-time-step>` with the integer time-step from which you wish to start the replay.
 
-## How to demo a simulation
+For instance, by visiting the following link, you will initiate a pre-simulated example, starting at time-step 1:  
+[http://localhost:8000/replay/July1_the_ville_isabella_maria_klaus-step-3-20/1/](http://localhost:8000/replay/July1_the_ville_isabella_maria_klaus-step-3-20/1/)
 
-compress_sim_storage 
+### Step 5. Demoing a Simulation
+You may have noticed that all character sprites in the replay look identical. We would like to clarify that the replay function is primarily intended for debugging purposes and does not prioritize optimizing the size of the simulation folder or the visuals. To properly demonstrate a simulation with appropriate character sprites, you will need to compress the simulation first. To do this, open the `compress_sim_storage.py` file located in the `reverie` directory using a text editor. Then, execute the `compress` function with the name of the target simulation as its input. By doing so, the simulation file will be compressed, making it ready for demonstration.
+
+To start the demo, go to the following address on your browser: `http://localhost:8000/demo/<simulation-name>/<starting-time-step>/<simulation-speed>`. Note that `<simulation-name>` and `<starting-time-step>` denote the same things as mentioned above. `<simulation-speed>` can be set to control the demo speed, where 1 is the slowest, and 5 is the fastest. For instance, visiting the following link will start a pre-simulated example, beginning at time-step 1, with a medium demo speed:  
+[http://localhost:8000/demo/July1_the_ville_isabella_maria_klaus-step-3-20/1/3/](http://localhost:8000/demo/July1_the_ville_isabella_maria_klaus-step-3-20/1/3/)
+
+### Tips
+We've noticed that OpenAI's API can hang when it reaches the hourly rate limit. When this happens, you may need to restart your simulation. For now, we recommend saving your simulation often as you progress to ensure that you lose as little of the simulation as possible when you do need to stop and rerun it. Running these simulations, at least as of early 2023, could be somewhat costly, especially when there are many agents in the environment.
+
+## Simulation Storage and Customization
+All simulations that you save will be located in `environment/frontend_server/storage`. Meanwhile, all compressed demos will be located in `environment/frontend_server/compressed_storage`. You can customize the agents in your simulation by manually authoring a new init simulation folder in `environment/frontend_server/storage`.
+
+## Citation 
+Please cite our paper if you use the code or data in this repository. 
+```
+@inproceedings{Park2023GenerativeAgents,  
+author = {Park, Joon Sung and O'Brien, Joseph C. and Cai, Carrie J. and Morris, Meredith Ringel and Liang, Percy and Bernstein, Michael S.},  
+title = {Generative Agents: Interactive Simulacra of Human Behavior},  
+year = {2023},  
+publisher = {Association for Computing Machinery},  
+address = {New York, NY, USA},  
+booktitle = {In the 36th Annual ACM Symposium on User Interface Software and Technology (UIST '23)},  
+keywords = {Human-AI interaction, agents, generative AI, large language models},  
+location = {San Francisco, CA, USA},  
+series = {UIST '23}
+}
+```
diff --git a/...frontend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/0.json b/...frontend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/0.json
@@ -0,0 +1,26 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 72,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 126,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
+
+
+
+
+
+
+
+
+
diff --git a/...frontend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1.json b/...frontend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
diff --git a/...rontend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/10.json b/...rontend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/10.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
diff --git a/...ontend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/100.json b/...ontend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/100.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
diff --git a/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1000.json b/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1000.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
diff --git a/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1001.json b/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1001.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
diff --git a/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1002.json b/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1002.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
diff --git a/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1003.json b/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1003.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
diff --git a/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1004.json b/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1004.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
diff --git a/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1005.json b/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1005.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
diff --git a/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1006.json b/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1006.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
diff --git a/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1007.json b/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1007.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
diff --git a/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1008.json b/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1008.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}
diff --git a/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1009.json b/...ntend_server/storage/July1_the_ville_isabella_maria_klaus-step-3-21/environment/1009.json
@@ -0,0 +1,17 @@
+{
+  "Isabella Rodriguez": {
+    "maze": "the_ville",
+    "x": 73,
+    "y": 14
+  },
+  "Klaus Mueller": {
+    "maze": "the_ville",
+    "x": 127,
+    "y": 46
+  },
+  "Maria Lopez": {
+    "maze": "the_ville",
+    "x": 123,
+    "y": 57
+  }
+}