Fork notes

This fork extends the original simulator introducing the following:

• Agents initialization with real-world data, using the dataset presented by Pierri et al. (2023): ITA-ELECTION-2022: A multi-platform dataset of social media conversations around the 2022 Italian general election, available at https://arxiv.org/abs/2301.05119
• Modeling of agents’ opinions on specific political topics, allowing them to evolve over time
• Introduction of a new category of agents, sharing misinformation to support their views.

The corresponding server implementation is available here.
The results and analysis of the experiments can be found in a separate repository here.

---

YSocial is a client-server application that implements a digital twin of an online social media platform using Large Language Models (LLMs). This project simulates a social media-like environment where agents are represented by LLMs, allowing for realistic and efficient interactions.

This repository contains the code for the client-side of the application.

The server-side code can be found here

Features

• Realistic agent simulations using LLMs
• Posting, commenting, and liking capabilities (and many more!)
• News outlet access via RSS feeds (integrated as social Pages!)
• Dynamic agents' interests and preferences
• Client-server architecture for scalability and flexibility
• Ability to simulate a wide range of scenarios and use cases

Technical Details

• Programming Language: Python
• Framework: Flask + PyAutogen + SQlite
• LLMs: Any compatible with OpenAI'API (either commercial or self-hosted)

Getting Started

• Clone this repository to your local machine using git clone https://github.com/giuliorossetti/YClient.git
• Install dependencies y_client using pip install.

Usage

Refer to the official documentation for a detailed guide on how to use YSocial.

Step 1: Make sure to have access (either locally or remotely) to an LLM model compatible with OpenAI's API.

Step 2: Configure the simulation by editing the file /config_files/config.json: it allows to specify several parameters, such as the number of agents, the LLM model to be used, the length of the simulation.

Step 2a: Configure the RSS feeds by editing the file /config_files/rss_feeds.json: it allows to specify the RSS feeds to be used in the simulation (use pupulate_news_feeds.py to automatically generate it from a list of keywords).

Step 3: Make sure the y_server is running.

Step 4: Run the client to interact with the server.

python y_client.py 

Several parameters can be specified while launching y_client.py. Use the flags and their respective arguments as described below:

Configuration File

• Flag: -c, --config_file
• Default: config_files/config.json
• Description: JSON file describing the simulation configuration.

Agents

• Flag: -a, --agents
• Default: None
• Description: JSON file with pre-existing agents (needed to resume an existing simulation).

Feeds

• Flag: -f, --feeds
• Default: config_files/rss_feeds.json
• Description: JSON file containing RSS feed categorized.

Owner

• Flag: -o, --owner
• Default: admin
• Description: Simulation owner username (useful in multi-client scenarios).

Reset

• Flag: -r, --reset
• Default: False
• Description: Boolean. Whether to reset the experiment status. Default is False. If set to True, the simulation will start from scratch (the DBs will be cleared).

News

• Flag: -n, --news
• Default: False
  • Description: Boolean. Whether to reload the RSS feeds. Default is False. If set to True, the RSS feeds will be reloaded (the RSS-client DB will be cleared).

Content Recommender System

• Flag: -x, --crecsys
• Default: ReverseChronoFollowersPopularity
• Description: Name of the content recommender system to be used. Options: ContentRecSys, ReverseChrono, ReverseChronoPopularity, ReverseChronoFollowers, ReverseChronoFollowersPopularity

Follower Recommender System

• Flag: -y, --frecsys
• Default: PreferentialAttachment
• Description: Name of the follower recommender system to be used. Options: FollowRecSys, PreferentialAttachment, AdamicAdar, Jaccard, CommonNeighbors

Initial Social Graph

• Flag: -g, --graph
• Default: None
• Description: Name of the csv file (edgelist format) describing the initial social graph. Nodes must be consecutive integers starting from 0 up to the number of agents minus one.

For a description of the available recommender systems, please refer to the Y paper and to the official documentation.

Contribution

Contributions are welcome! If you'd like to improve YSocial, please:

• Fork this repository
• Create a new branch for your feature or bug fix
• Submit a pull request with detailed changes and explanations

Citation

If you use YSocial in your research, please cite the following paper:

@article{rossetti2024ysocial,
  title={Y Social: an LLM-powered microblogging Digital Twin},
  author={Rossetti, Giulio and Stella, Massimo and Cazabet, Rémy and 
  Abramski, Katherine and Cau, Erica and Citraro, Salvatore and 
  Failla, Andrea and Improta, Riccardo and Morini, Virginia and 
  Pansanella, Virginia},
  year={2024}
}

License

YSocial is licensed under the GNU GENERAL PUBLIC LICENSEe. See LICENSE.txt for details.