YSocial is a client-server application that implements a digital twin of a microblogging 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 server-side of the application.

The client-side code can be found here

For more information, please refer to the official documentation

Features

• Realistic agent simulations using LLMs
• Microblogging platform with posting, commenting, and liking capabilities
• Client-server architecture for scalability and flexibility
• Support for various user interactions (e.g., posting, commenting, liking)
• Ability to simulate a wide range of scenarios and use cases

Technical Details

• Programming Language: Python
• Framework: Flask + SQlite

Getting Started

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

Usage

Set the server preferences modifying the file config_files/exp_config.json:

{
  "name": "local_test",
  "host": "0.0.0.0",
  "port": 5010,
  "reset_db": "True",
  "modules": ["news", "voting"]
}

For more control over the database, you can optionally specify a database_uri:

{
  "name": "local_test",
  "host": "0.0.0.0",
  "port": 5010,
  "reset_db": "True",
  "modules": ["news", "voting"],
  "database_uri": "sqlite:////absolute/path/to/database.db"
}

Or for PostgreSQL:

{
  "name": "local_test",
  "host": "0.0.0.0",
  "port": 5010,
  "modules": ["news", "voting"],
  "database_uri": "postgresql://user:password@localhost/dbname"
}

Configuration parameters:

• name - Name of the experiment (used for default SQLite database path under experiments/ folder if database_uri is not specified)
• host - IP address of the server
• port - Port number for the server
• reset_db - (Optional) Flag to reset/recreate the database at server start (default: "False")
• modules - List of additional modules to load (e.g., news, voting). YClient must use the same modules
• database_uri - (Optional) Full database URI. If specified, overrides the default SQLite path. Supports SQLite and PostgreSQL

Once the simulation is configured, start the YServer with the following command:

Development Server

For development and testing:

python y_server_run.py

Production Deployment with Gunicorn

For production environments, use Gunicorn instead of the built-in Flask development server:

# Basic usage (uses config_files/exp_config.json)
gunicorn wsgi:app

# With gunicorn configuration file
gunicorn -c gunicorn_config.py wsgi:app

# With custom experiment configuration file
YSERVER_CONFIG=/path/to/your/config.json gunicorn -c gunicorn_config.py wsgi:app

# With command-line options (4 workers, binding to all interfaces on port 5010)
gunicorn -w 4 -b 0.0.0.0:5010 wsgi:app

# With more advanced options
gunicorn -w 4 -b 0.0.0.0:5010 --timeout 120 --access-logfile - --error-logfile - wsgi:app

Running Multiple Instances:

When running multiple YServer instances on different ports simultaneously, start each in a separate subprocess with its own YSERVER_CONFIG environment variable. Important: Specify the database_uri in each config file to set the database at startup and avoid calling change_db after workers are created, which can cause stability issues.

import subprocess
import os

# Config file 1 (config1.json):
# {
#   "host": "0.0.0.0",
#   "port": 5010,
#   "database_uri": "sqlite:////path/to/db1.db"
# }

# Config file 2 (config2.json):
# {
#   "host": "0.0.0.0", 
#   "port": 5020,
#   "database_uri": "sqlite:////path/to/db2.db"
# }

# Start first instance on port 5010
env1 = os.environ.copy()
env1['YSERVER_CONFIG'] = '/path/to/config1.json'
proc1 = subprocess.Popen(['gunicorn', '-c', 'gunicorn_config.py', 'wsgi:app'], env=env1)

# Start second instance on port 5020
env2 = os.environ.copy()
env2['YSERVER_CONFIG'] = '/path/to/config2.json'
proc2 = subprocess.Popen(['gunicorn', '-c', 'gunicorn_config.py', 'wsgi:app'], env=env2)

Each Gunicorn process runs in its own Python interpreter with its own environment, ensuring configurations don't conflict. By setting database_uri in the config file, the database is configured at application startup before workers are forked, avoiding the need for runtime change_db calls.

macOS Compatibility:

The gunicorn configuration file (gunicorn_config.py) automatically detects macOS and disables preload_app to prevent fork safety crashes with CoreFoundation, Objective-C runtime, and other macOS frameworks. These frameworks cannot be safely used after fork() without exec(), which would cause SIGSEGV errors.

When using -c gunicorn_config.py, the server will:

• Automatically disable preload_app on macOS (slightly slower startup, but stable)
• Set OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES as an additional safeguard
• Work normally on Linux/Unix with preload_app enabled for better performance

If you encounter fork-related errors on macOS, ensure you're using the gunicorn configuration file with the -c flag.

Modules

• News: This module allows the server to access online news sources leveraging RSS feeds.
• Voting: This module allows the agents to cast their voting intention after interacting with peers contents (designed to perform political debate simulation).

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.