(NeurIPS' 24) Large Language Models as Urban Residents: An LLM Agent Framework for Personal Mobility Generation

📖 Description

Welcome to the official implementation of LLMob, as described in our NeurIPS'24 paper Large Language Models as Urban Residents: An LLM Agent Framework for Personal Mobility Generation. This project demonstrates how Large Language Models (LLMs) can be leveraged to generate personal mobility trajectories based on real-world data.

LLMob is an intuitive framework that builds reasoning logic for LLMs in the context of personal activity trajectory generation.

Figure 1: The LLMob Framework Architecture.

Figure 2: Illustration of activity trajectory generated by LLM agent.

⭐ Key Components

• /engine/agent.py: Generate personal activity trajectory according to real-world check-in data.
• /engine/persona_identify.py: Phase 1 Self-consistent activity pattern identification.
• /engine/trajectory_generate.py: Phase 2 Activity generation based on Identified Pattern and Motivation.
• /engine/utilities/retrieval_helper.py: Function related to learning based motivation retrieval.
• /prompt_template: Prompt template used in this project.

📦 Data

Trajectory Data

• /data/2019/: Personal trajectories from 2019.
• /data/2021/: Personal trajectories from 2021.
• /data/20192021/: Combined trajectories from 2019 and 2021.

Mapping Files

• /data/loc_map.pkl:
  Maps each unique location to a name and unique ID.

  • Key: location name + latitude + longitude
  • Value: location name + unique ID

• /data/pos_map.pkl:
  Maps each unique location to a node ID in the city network.

  • Key: location name + latitude + longitude
  • Value: city network node ID

• /data/location_activity_map.pkl:
  Maps locations to activity categories (from Foursquare).

  • Key: location name
  • Value: activity category

⚙️ Usage

To get started with LLMob, follow these steps:

git clone https://github.com/Wangjw6/LLMob.git
cd LLMob
conda env create -f environment.yml
conda activate llm
# Run the LLMob agent to generate 2019 data then evaluate, mode 0 for learning based retrieval, 1 for evolving based retrieval
python generate.py --dataset 2019 --mode 1 
python evaluate.py --dataset 2019 --mode 1 

# Run the LLMob agent to generate 2021 data then evaluate, mode 0 for learning based retrieval, 1 for evolving based retrieval
python generate.py --dataset 2021 --mode 1 
python evaluate.py --dataset 2021 --mode 1 

# Run the LLMob agent to generate 2021 data based on 2019 data then evaluate, mode 0 for learning based retrieval, 1 for evolving based retrieval
python generate.py --dataset 20192021 --mode 1 
python evaluate.py --dataset 20192021 --mode 1 

You should also add your own OpenAI API key in the ./config/key.yaml file.

📚 BibTex Citation

If you would like to cite our work, please use:

@article{jiawei2024large,
  title={Large language models as urban residents: An llm agent framework for personal mobility generation},
  author={JIAWEI, WANG and Jiang, Renhe and Yang, Chuang and Wu, Zengqing and Shibasaki, Ryosuke and Koshizuka, Noboru and Xiao, Chuan and others},
  journal={Advances in Neural Information Processing Systems},
  volume={37},
  pages={124547--124574},
  year={2024}
}

🌷 Acknowledgments

Our implementation adapts several open-source ChatGPT application and have extensively modified it to our purposes. We thank the authors for sharing their implementations and related resources:

• Generative Agents: Interactive Simulacra of Human Behavior

• MetaGPT

The raw data used in this project is from Foursquare API. We select the data with enough records and preprocess them before using in our project.