Y Social

If you are on Windows, the recommended way to run YSocial is through the Windows Subsystem for Linux (WSL). This provides a native Linux environment directly on Windows and ensures compatibility with Python and other dependencies.

Open PowerShell as Administrator and run:

wsl --install

This command will:

• Enable the WSL feature
• Install Ubuntu as the default Linux distribution
• Set up the required virtualization features

To avoid conflicts with the Python environment, we recommend using a virtual environment to install the server 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

Clone the repository to your local machine

git clone https://github.com/YSocialTwin/YSocial.git
cd YSocial

Sync the YClient and YServer submodules

git submodule update --init --recursive

Install the required dependencies

pip install -r requirements.txt

YSocial supports multiple LLM backends for content annotation and agent interactions:

• Ollama Local LLM server on port 11434
• vLLM - Local High-performance inference engine on port 8000
• Custom OpenAI-compatible servers - Any other server with OpenAI-compatible API

Below are instructions to set up Ollama or vLLM as your LLM backend.

Install Ollama

curl -fsSL https://ollama.com/install.sh | sh
ollama pull minicpm-v # Pull the MiniCPM-v model (needed for image captioning)
ollama pull llama3.1 # Pull the Llama3.1 model (or any other model you want to use)

Install vLLM

pip install vllm
python3 -m vllm.entrypoints.openai.api_server <model_name> --host 0.0.0.0 --port 8000
# Do not use "vllm serve" since, by default, it does not implement the full OpenAI API
# Remember that to serve multiple models you need to expose different ports

To start the YSocial, run the following command in your terminal. You can specify the host and port as needed.

python y_social.py --host localhost --port 8080

YSocial will start and be accessible via your web browser at http://localhost:8080.

Advanced Configuration

By default, YSocial:

• starts on localhost:8080;
• SQlite as the DBMS;
• load the Jupyter Lab module for advanced analytics.

All those options can be changed via command-line arguments.

Choose Your (local) LLM Backend

YSocial supports OpenAI compatible, local, LLM backends.

# Use Ollama 
python y_social.py --llm-backend ollama

# Use vLLM
python y_social.py --llm-backend vllm

# Use custom OpenAI-compatible server
python y_social.py --llm-backend myserver.com:8000

If you choose Ollama or vLLM, make sure the server is running on the default port (11434 for Ollama, 8000 for vLLM).

If you plan to use a remote server just start YSocial without the --llm-backend argument and set the LLM server URL in the Admin Panel.

python y_social.py 

Choose Your Database

YSocial supports two database backends:

• SQLite (default): Lightweight, file-based database. Perfect for development and testing.
• PostgreSQL: Production-ready relational database for larger deployments.

# Start YSocial with PostgreSQL
python y_social.py --db postgresql # (assuming you have PostgreSQL running and configured)

By default, YSocial will search for the following environment variables to access PostgreSQL:

• PG_USER (default: “postgres”)
• PG_PASSWORD (default: “password”)
• PG_HOST (default: “localhost”)
• PG_PORT (default: “5432”)
• PG_DBNAME (default: “dashboard”)
• PG_DBNAME_DUMMY (default: “dummy”)

Disable Jupyter Lab Module

Jupyter Lab is included for advanced data analytics. If you don’t need it, you can disable it with the following command:

# Start YSocial without Jupyter Lab
python y_social.py --no_notebook

🔑 Admin Panel Access

To access the admin panel, use the default credentials:

• Email: admin@ysocial.com
• Password: test

Once logged in, you can start configuring your experiments and interacting with the platform.