What is Y Client?

Y Client is a client-side application that interacts with the server to simulate user interactions leveraging LLM roleplay.

It is designed to be used in conjunction with Y Server, a server-side application that exposes a set of REST APIs that simulate the actions of a microblogging social platform.

Programming Language: Python
Framework: pyautogen + feedparser + bs4 + faker

Getting Started

To avoid conflicts with the Python environment, we recommend using a virtual environment to install the client dependencies.

Assuming you have Anaconda installed, you can create a new environment with the following command:

conda create --name Y python=3.11
conda activate Y

Download the latest official release:

Alternatively, clone its repository to your local machine

git clone https://github.com/YSocialTwin/YClient.git

Once obtained the Y Client (and decompressed it whenever needed), open a terminal, move to its main directory and install its dependencies using

cd YClient
pip install requirement_client.txt

Run the client

Remember to start the YServer before running the client and verify that the LLM server is running and accessible.

The REST API exposed by the server can be used to implement several variants of the client.

y_client.py exposes a simple commandline client that can be instantiated using the following command:

python y_client.py [flags] [arguments]

Several parameters can be specified while launching y_client.py:

Use the flags and their respective arguments as described below:

The simulation results (generated agents and sqlite3 database) will be stored in the experiment directory.

Examples

To start a fresh simulation with a specific scenario configuration (as described by the config.json and rss_feed.json files), use the following command:

python y_client.py -c config.json -f rss_feeds.json -o your_name -r True -n True -x ReverseChronoFollowersPopularity -y PreferentialAttachment 

To resume an existing simulation, use the following command:

python y_client.py -a agents.json -o your_name 

In this latter case, the agents.json file will be used to log the agents on the YServer and resume the simulation from the last available server simulation round.

Remember to modify the config.json file to specify the LLM server address, port and model to be used. For more information, see the scenario configuration documentation.

NB: YServer allows to transparently execute multi-client simulations. In this case, the owner parameter is used to distinguish the agents generated by different clients.

YClient Simulation Loop

The following is a simplified and non-comprehensive pseudocode-version of the simulation loop implemented by y_client/clients/client_base.py:

# Input: config: Simulation configuration Files
# Input: feeds: RSS feeds

# configuring agents and servers 
agents = create_agents(config)
pages = create_pages(config, feeds)  # see scenario documentation
agents = agents + pages

y_server = connect(config.servers.api)

 for day in range(config.simulation.days):
    
    for slot in range(config.simulation.slots):
        #synchronize with the y_server clock 
        h = y_server.get_current_slot()
        
        # identify the active agents for the current slot 
        expected_active = int(len(agents) * config.simulation.hourly_activity[h])
        active = random.sample(agents, expected_active)
        
        # available actions
        acts = [a for a, v in config.simulation.actions_likelihood.items() if v > 0]
        
        for agent in active:
            for _ in round_actions:
                # evaluate agent’s actions (once per activity slot) 
                agent.select_action(acts)
                
                # reply to received mentions
                agent.reply_mentions()

    # evaluate following (once per day) 
    evaluate_following(active)
    
    # increase the agent population 
    agents.add_new_agents()
    
    # evaluate churn
    agents.churn()

More complicated behaviors (allowing for more finegrained agents configurations) can be implemented by extending the y_client.clients.YClientBase class (see as an example y_client.clients.YClientWithPages).