### Install and Run Redis Stack on MacOS

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/index.mdx

Instructions for installing Redis Stack using Homebrew and starting the server. Also shows how to set the REDIS_OM_URL environment variable.

```bash
brew tap redis-stack/redis-stack
brew install redis-stack
```

```bash
redis-stack-server --daemonize yes
```

```bash
conda env config vars set REDIS_OM_URL="redis://user:password@host:port"
```

--------------------------------

### Install Sotopia with Extra Dependencies

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/index.mdx

Install Sotopia with optional dependencies for examples and chat. If developing with uv, sync dependencies using `uv sync --extra examples --extra api`.

```bash
pip install sotopia[examples, chat]
```

```bash
uv sync --extra examples --extra api
```

--------------------------------

### Install Sotopia with uv

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/index.mdx

Recommended installation method using uv. This command installs the Sotopia package.

```bash
uv pip install sotopia
```

--------------------------------

### Install Sotopia from Source

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/index.mdx

Clone the Sotopia repository and install the package from source using uv to sync all extras.

```bash
git clone git@github.com:sotopia-lab/sotopia.git;
cd sotopia;
uv sync --all-extras
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/sotopia-lab/sotopia/blob/main/examples/experimental/interview_openhands/readme.md

Install all project dependencies using Poetry after navigating to the project directory.

```bash
poetry install
```

--------------------------------

### Run FastAPI Example

Source: https://github.com/sotopia-lab/sotopia/blob/main/sotopia/api/README.md

Execute an example script that utilizes the FastAPI server.

```bash
uv run python examples/fast_api_example.py
```

--------------------------------

### Python WebSocket Client Example

Source: https://github.com/sotopia-lab/sotopia/blob/main/sotopia/api/README.md

Example demonstrating how to connect to the WebSocket server using Python's aiohttp library, send a simulation start message, and receive messages.

```python
import aiohttp
import asyncio
import json

async def main():
    async with aiohttp.ClientSession() as session:
        async with session.ws_connect(f'ws://{API_BASE}/ws/simulate/?token={YOUR_TOKEN}') as ws:
            start_message = {
                "type": "START_SIM",
                "data": {
                    "env_id": "{ENV_ID}",
                    "agent_ids": ["{AGENT1_PK}", "{AGENT2_PK}"],
                },
            }
            await ws.send_json(start_message)

            async for msg in ws:
                if msg.type == aiohttp.WSMsgType.TEXT:
                    print(f"Received: {msg.data}")
                elif msg.type == aiohttp.WSMsgType.CLOSED:
                    break
                elif msg.type == aiohttp.WSMsgType.ERROR:
                    break

# Note: Replace API_BASE, YOUR_TOKEN, ENV_ID, AGENT1_PK, AGENT2_PK with actual values.
# asyncio.run(main())
```

--------------------------------

### Run Interview OpenHands Example

Source: https://github.com/sotopia-lab/sotopia/blob/main/examples/experimental/interview_openhands/readme.md

Command to execute the specific interview setting example using the provided TOML configuration file.

```bash
uv run aact run-dataflow examples/experimental/interview_openhands/interview_openhands.toml
```

--------------------------------

### Connect to WebSocket and Start Simulation

Source: https://github.com/sotopia-lab/sotopia/blob/main/sotopia/api/README.md

This Python script demonstrates how to connect to the Sotopia WebSocket API, send a simulation start message, and receive real-time updates. Ensure you have aiohttp and asyncio installed. Replace placeholders like YOUR_TOKEN, {ENV_ID}, {AGENT1_PK}, and {AGENT2_PK} with actual values.

```python
import aiohttp
import asyncio
import json

async def main():
    async with aiohttp.ClientSession() as session:
        async with session.ws_connect(f'ws://{API_BASE}/ws/simulation?token={YOUR_TOKEN}') as ws:
            start_message = {
                "type": "START_SIM",
                "data": {
                    "env_id": "{ENV_ID}",
                    "agent_ids": ["{AGENT1_PK}", "{AGENT2_PK}"],
                },
            }
            await ws.send_json(start_message)

            async for msg in ws:
                if msg.type == aiohttp.WSMsgType.TEXT:
                    print(f"Received: {msg.data}")
                elif msg.type == aiohttp.WSMsgType.CLOSED:
                    break
                elif msg.type == aioiohttp.WSMsgType.ERROR:
                    break
```

--------------------------------

### Install Sotopia Locally

Source: https://github.com/sotopia-lab/sotopia/blob/main/README.md

Installs Sotopia and its dependencies using uv. Ensure you are in a virtual environment.

```bash
pip install uv; uv sync --all-extras
uv run sotopia install
```

--------------------------------

### Run Realtime Chat Example

Source: https://github.com/sotopia-lab/sotopia/blob/main/examples/experimental/realtime/readme.md

Execute the realtime chat example using the provided command. This command assumes you are in the repository folder.

```python
uv run --extra realtime aact run-dataflow examples/experimental/realtime/realtime_chat.toml
```

--------------------------------

### Example Gin-Config Experiment Execution

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/examples/experiment.md

An example demonstrating how to run an experiment with multiple gin configuration files and specific parameter overrides for environment IDs, model, batch size, and other settings.

```bash
python examples/experiment_eval.py --gin_file sotopia_conf/generation_utils_conf/generate.gin --gin_file sotopia_conf/server_conf/server.gin --gin_file sotopia_conf/run_async_server_in_batch.gin '--gin.ENV_IDS=["01H7VFHPDZVVCDZR3AARA547CY"]' '--gin.AGENT1_MODEL="gpt-4"' '--gin.BATCH_SIZE=20' '--gin.PUSH_TO_DB=False' '--gin.TAG="test"'
```

--------------------------------

### OpenHands Node Output Example

Source: https://github.com/sotopia-lab/sotopia/blob/main/examples/experimental/interview_openhands/readme.md

Example output indicating a successful connection and initialization of the OpenHands runtime.

```bash
16:41:26 - openhands:INFO: openhands_node.py:120 - --------------------
16:41:26 - openhands:INFO: openhands_node.py:121 - RUNTIME CONNECTED
16:41:26 - openhands:INFO: openhands_node.py:122 - --------------------
16:41:26 - openhands:INFO: openhands_node.py:127 - Runtime initialization took 157.77 seconds.
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/contribution/contribution.md

Use uv to install all project dependencies, including extras. Ensure Python 3.10+ and uv are installed first.

```bash
uv sync --all-extras
```

--------------------------------

### Install Sotopia and Dependencies

Source: https://context7.com/sotopia-lab/sotopia/llms.txt

Installs Sotopia and its dependencies using uv. Downloads default datasets and configures storage backend (Redis or local JSON).

```bash
pip install uv
uv sync --all-extras
uv run sotopia install        # downloads default datasets into Redis or ~/.sotopia/data/
```

```bash
# Redis backend (recommended for production)
docker run -d -p 6379:6379 redis/redis-stack-server:latest
export SOTOPIA_STORAGE_BACKEND=redis
export REDIS_OM_URL=redis://localhost:6379
export OPENAI_API_KEY=sk-...
```

```bash
# Local JSON backend (development / no Redis needed)
export SOTOPIA_STORAGE_BACKEND=local
export OPENAI_API_KEY=sk-...
```

--------------------------------

### Set Up Environment Variables

Source: https://github.com/sotopia-lab/sotopia/blob/main/examples/experimental/interview_openhands/readme.md

Copy the example environment file and update it with your specific API keys and URLs. Ensure to replace placeholder values.

```bash
cp .env.example .env
```

```plaintext
MODAL_API_TOKEN_ID=your_actual_modal_api_token_id
MODAL_API_TOKEN_SECRET=your_actual_modal_api_token_secret
```

--------------------------------

### Install Poetry

Source: https://github.com/sotopia-lab/sotopia/blob/main/examples/experimental/interview_openhands/readme.md

Install Poetry, a dependency management tool for Python, using the provided installation script.

```bash
curl -sSL https://install.python-poetry.org | python3 -
```

--------------------------------

### Set Up Redis for Sotopia

Source: https://github.com/sotopia-lab/sotopia/blob/main/README.md

Starts a Redis server using Docker, which is the recommended method for setting up the Redis backend for Sotopia.

```bash
docker run -d -p 6379:6379 redis/redis-stack-server:latest
```

--------------------------------

### Install PortAudio Dependency

Source: https://github.com/sotopia-lab/sotopia/blob/main/examples/experimental/realtime/readme.md

Install the PortAudio library, which is required to run the realtime demo. Instructions are provided for macOS and Linux.

```bash
# On Mac
brew install portaudio

# On Linux
apt-get install portaudio19-dev
```

--------------------------------

### Start Redis with Dump File

Source: https://github.com/sotopia-lab/sotopia/blob/main/scripts/README.md

Starts a Redis server, loading a provided dump file. It handles existing instances, uses redis-stack-server if available, and ensures Redis is ready before proceeding.

```bash
./scripts/start_redis_with_dump.sh
```

--------------------------------

### Run Redis Stack with Docker

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/index.mdx

This command starts a Redis Stack server using Docker. Ensure you have Docker installed and running. Mount a local directory for data persistence.

```bash
docker run -d --name redis-stack -p 6379:6379 -p 8001:8001 -v <your_path>/redis-data:/data/ redis/redis-stack:latest
```

--------------------------------

### Install uv and Sync Dependencies

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/contribution/contribution.md

Installs the uv package manager and synchronizes all project dependencies. Ensure you have Python 3.10+ installed.

```bash
pip install uv; uv sync --all-extras
```

--------------------------------

### Install Sotopia with Pip

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/index.mdx

Use this command to install the Sotopia package. Ensure you have pip installed. The REDIS_OM_URL environment variable is required for Redis operations.

```bash
pip install sotopia
sotopia install
export REDIS_OM_URL="redis://localhost:6379"
```

--------------------------------

### Start Redis Server

Source: https://github.com/sotopia-lab/sotopia/blob/main/examples/experimental/negotiation_arena/README.md

Command to start the Redis server. Ensure you specify the correct path to your Redis data directory.

```bash
redis-stack-server --dir [path-to-your-redis-data]
```

--------------------------------

### Run Easy Sample Server with Default Parameters

Source: https://github.com/sotopia-lab/sotopia/blob/main/README.md

Launches a demo server with default parameters using specified models and a uniform sampler. Ensure you have datasets installed to run locally.

```python
import asyncio
from sotopia.samplers import UniformSampler
from sotopia.server import run_async_server

asyncio.run(
    run_async_server(
        model_dict={
            "env": "gpt-4",
            "agent1": "gpt-4o-mini",
            "agent2": "gpt-4o-mini",
        },
        sampler=UniformSampler(),
    )
)
```

--------------------------------

### Usage Example of BaseSampler

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/samplers/base_sampler.md

Demonstrates how to use the BaseSampler by defining a custom agent, initializing the sampler, and then calling the `sample` method. The example iterates over the generated samples, printing the environment and agents. Note that the `sample` method itself must be implemented in a subclass.

```python
from sotopia.agents.base_agent import BaseAgent
from sotopia.database.persistent_profile import AgentProfile, EnvironmentProfile
from sotopia.envs.parallel import ParallelSotopiaEnv

# Define a custom agent class inheriting from BaseAgent
class CustomAgent(BaseAgent):
    pass

# Initialize the BaseSampler
sampler = BaseSampler()

# Sample an environment and agents
samples = sampler.sample(agent_classes=[CustomAgent], n_agent=3, size=5)

# Iterate over the generated samples
for env, agents in samples:
    print(f"Environment: {env}")
    print(f"Agents: {agents}")
```

--------------------------------

### Download and Install Redis Stack

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/tutorials/1.2-browse-data.ipynb

Installs Redis Stack and necessary dependencies for running Sotopia data services. This includes downloading the Redis server archive and installing libssl1.1 for compatibility.

```bash
# @title Download Redis: This code block is exactly the same as [Tutorial 1.1](https://colab.research.google.com/drive/14hJOfzpA37PRUzdlFgiqVzUGIhhngqnz?usp=sharing).
%%capture
!curl -fsSL https://packages.redis.io/redis-stack/redis-stack-server-7.2.0-v10.focal.x86_64.tar.gz -o redis-stack-server.tar.gz
!tar -xvf redis-stack-server.tar.gz
# Installs libssl1.1 for Ubuntu 22 source: https://stackoverflow.com/questions/72133316/libssl-so-1-1-cannot-open-shared-object-file-no-such-file-or-directory
!wget http://nz2.archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
!sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb
%pip install redis
```

--------------------------------

### Migration Summary Example

Source: https://github.com/sotopia-lab/sotopia/blob/main/scripts/README.md

Example output showing a summary of records exported per model during the migration process, including counts of exported records and errors.

```text
Export Summary
============================================================
  ✓ Annotator: 3 records exported (0 errors)
  ✓ EnvAgentComboStorage: 450 records exported (0 errors)
  ✓ AnnotationForEpisode: 439 records exported (0 errors)
============================================================
Total: 892 records exported (0 errors)
```

--------------------------------

### Initialize ParallelSotopiaEnv Instance

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/envs/parallel.md

Example of how to instantiate the ParallelSotopiaEnv with custom action types, action order, and model name.

```python
env = ParallelSotopiaEnv(
    available_action_types={"none", "speak", "action"},
    action_order="round-robin",
    model_name="gpt-3.5-turbo"
)
```

--------------------------------

### Build Documentation Locally

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/contribution/contribution.md

Build the project documentation locally using Bun. This command navigates to the docs directory and starts the development server for the documentation.

```shell
cd docs; bun run dev
```

--------------------------------

### Install Sotopia with Redis Stack

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/index.mdx

Use this command to automatically install Sotopia and its Redis Stack dependency.

```bash
sotopia install
```

--------------------------------

### Install Sotopia and Configure Redis Connection

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/tutorials/1.2-browse-data.ipynb

Installs the Sotopia library and sets the REDIS_OM_URL environment variable to point to the local Redis instance. This is necessary for Sotopia to interact with the database.

```bash
# @title First, install sotopia
%%capture
%pip install sotopia
import os

os.environ["REDIS_OM_URL"] = "redis://:@localhost:6379"
```

--------------------------------

### Install Pre-commit Hooks for Linting

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/contribution/contribution.md

Install the pre-commit framework to automatically run linting and other code quality checks on each commit. This helps maintain code standards.

```shell
uv run pre-commit install
```

--------------------------------

### Initialize and Use LoggingCallbackHandler

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/generation_utils/langchain_callback_handler.md

Demonstrates how to configure logging, initialize the LoggingCallbackHandler, and capture a prompt during a chat model start event. The captured prompt can then be retrieved.

```python
import logging
from your_module import BaseMessage, LoggingCallbackHandler

# Configuration of logging
logging.basicConfig(level=15)

# Initialize the handler
handler = LoggingCallbackHandler(name="langchain")

# Example usage with mock data
serialized = {}
messages = [[BaseMessage(content="Hello, how can I assist you today?")]]

handler.on_chat_model_start(serialized=serialized, messages=messages)
print(handler.retrieve_prompt())  # Output: "Hello, how can I assist you today?"
```

--------------------------------

### Initialize and Use Llama2 Model

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/generation_utils/llama2.md

Demonstrates how to initialize the Llama2 model, prepare messages, and generate a response. Ensure LangChain and necessary components are installed.

```python
from langchain.schema import HumanMessage

# Initialize the Llama2 model
llama2_model = Llama2()

# Prepare input messages
messages = [HumanMessage(content="List the best restaurants in SF")]

# Generate a response
chat_result = llama2_model._generate(messages)

# Retrieve and print the response
response_message = chat_result.generations[0].message
print(response_message.content)
```

--------------------------------

### Install redis-stack

Source: https://github.com/sotopia-lab/sotopia/blob/main/scripts/README.md

Command to install redis-stack using Homebrew, required for loading dump files with Redis modules like RediSearch or RedisJSON.

```bash
brew install redis-stack
```

--------------------------------

### MessengerMixin Usage Example

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/messages/messenger.md

Demonstrates how to instantiate MessengerMixin, receive messages, and reset the inbox. Ensure Message class and MessengerMixin are correctly imported.

```python
from .message_classes import Message
from .your_module import MessengerMixin

# Create an instance of MessengerMixin
messenger = MessengerMixin()

# Create a message object (assuming Message class is defined)
message = Message("Hello, World!")

# Receive a message from 'Alice'
messenger.recv_message("Alice", message)

# Check the current inbox
print(messenger.inbox)  # Output: [('Alice', <Message object>)]

# Reset the inbox
messenger.reset_inbox()

# Check the inbox again
print(messenger.inbox)  # Output: []
```

--------------------------------

### Usage Example

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/generation_utils/llama2.md

Demonstrates how to initialize and use the Llama2 model to generate a chat response.

```APIDOC
## Usage Example

```python
from langchain.schema import HumanMessage

# Initialize the Llama2 model
llama2_model = Llama2()

# Prepare input messages
messages = [HumanMessage(content="List the best restaurants in SF")]

# Generate a response
chat_result = llama2_model._generate(messages)

# Retrieve and print the response
response_message = chat_result.generations[0].message
print(response_message.content)
```
```

--------------------------------

### Download and Run Redis Stack on Linux

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/index.mdx

Steps to download, extract, and run the Redis Stack server on Linux. Includes setting the PATH and starting the server as a daemon.

```bash
# if you are using Ubunutu 20.04
curl -fsSL https://packages.redis.io/redis-stack/redis-stack-server-7.2.0-v10.focal.x86_64.tar.gz -o redis-stack-server.tar.gz
tar -xvzf redis-stack-server.tar.gz
export PATH=$(pwd)/redis-stack-server-7.2.0-v10/bin:$PATH
# if you are using Ubunutu 22.04, please do an extra step
wget http://nz2.archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb
```

```bash
./redis-stack-server-7.2.0-v10/bin/redis-stack-server --daemonize yes
```

```bash
conda env config vars set REDIS_OM_URL="redis://user:password@host:port"
```

--------------------------------

### Run Async Server for ParallelSotopiaEnv

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/concepts/environments.md

Demonstrates the simplest way to use ParallelSotopiaEnv by running an asynchronous server. This setup requires specifying model configurations for the environment and agents, along with a sampler.

```python
asyncio.run(
    run_async_server(
        model_dict={
            "env": "gpt-4",
            "agent1": "gpt-3.5-turbo",
            "agent2": "gpt-3.5-turbo",
        },
        sampler=UniformSampler(),
    )
)
```

--------------------------------

### Step Through ParallelSotopiaEnv Actions

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/envs/parallel.md

Example of executing actions in the ParallelSotopiaEnv and receiving the next state, rewards, done flags, truncations, and info.

```python
next_obs, rewards, done, truncations, info = env.step(actions)
```

--------------------------------

### Deploy FastAPI Server to Modal

Source: https://github.com/sotopia-lab/sotopia/blob/main/sotopia/api/README.md

Deploy the FastAPI server to Modal. Ensure you have a Modal account and are logged in via `modal setup`.

```bash
modal deploy scripts/modal/modal_api_server.py
```

--------------------------------

### Start Redis Server in Daemon Mode

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/tutorials/1.1-setup.ipynb

Spins up the Redis server in the background using the downloaded Redis Stack executable. Ensure no errors are reported to confirm successful startup.

```bash
# @title Just one line of code to spin up your redis server:


!./redis-stack-server-7.2.0-v10/bin/redis-stack-server --daemonize yes
```

--------------------------------

### UniformSampler Usage Example

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/samplers/uniform_sampler.md

Demonstrates how to instantiate and use the UniformSampler to generate environment-agent combinations. Ensure agent_classes and agents_params lists match the specified n_agent.

```python
from sotopia.agents.some_agent import SomeAgent
from sotopia.samplers.uniform_sampler import UniformSampler

sampler = UniformSampler()
agent_classes = [SomeAgent, SomeAgent]
agents_params = [{"param1": "value1"}, {"param2": "value2"}]

for env, agents in sampler.sample(agent_classes, n_agent=2, agents_params=agents_params):
    print(env)
    for agent in agents:
        print(agent)
```

--------------------------------

### Configure Sotopia Environment Variables

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/tutorials/1.1-setup.ipynb

Installs the sotopia package and sets the necessary environment variables, REDIS_OM_URL for the Redis connection and OPENAI_API_KEY retrieved from user data.

```python
# @title Run the following cell to add it to the environment variable.
%%capture
%pip install sotopia
import os
from google.colab import userdata

os.environ["REDIS_OM_URL"] = "redis://:@localhost:6379"
os.environ["OPENAI_API_KEY"] = userdata.get("OPENAI_API_KEY")
```

--------------------------------

### Access Local Storage Data with Python

Source: https://github.com/sotopia-lab/sotopia/blob/main/scripts/README.md

Example of how to use Sotopia's database models when the local storage backend is enabled. The `SOTOPIA_STORAGE_BACKEND=local` environment variable is automatically detected.

```python
from sotopia.database import AgentProfile, Annotator

# Automatically uses local storage when SOTOPIA_STORAGE_BACKEND=local
annotators = Annotator.all()
for annotator in annotators:
    print(f"{annotator.name}: {annotator.email}")
```

--------------------------------

### Set and Get Agent Goal

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/agents/base_agent_api_docs.md

Shows how to set and retrieve the agent's goal using the `goal` property. Asserts that the goal is correctly stored and accessible.

```python
agent = BaseAgent(agent_name="John Doe")
agent.goal = "Obtain food"
assert agent.goal == "Obtain food"
```

--------------------------------

### Synchronous Action Function Example

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/generation_utils/sync.md

Shows how to call a synchronous version of an asynchronous action function. This is useful for performing actions that were originally designed as async but need to be invoked synchronously.

```python
result = generate_action(arg1, arg2, ...)
```

--------------------------------

### Download and Install Redis Stack and Dependencies

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/tutorials/1.1-setup.ipynb

Downloads Redis Stack server 7.2.0, extracts it, and installs the libssl1.1 dependency required for older Ubuntu versions. It also installs the redis Python package.

```python
# @title The following block downloads Redis stack server 7.2.0, and libssl 1.1.
%%capture
!curl -fsSL https://packages.redis.io/redis-stack/redis-stack-server-7.2.0-v10.focal.x86_64.tar.gz -o redis-stack-server.tar.gz
!tar -xvf redis-stack-server.tar.gz
# Installs libssl1.1 for Ubuntu 22 source: https://stackoverflow.com/questions/72133316/libssl-so-1-1-cannot-open-shared-object-file-no-such-file-or-directory
!wget http://nz2.archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
!sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb
%pip install redis
```

--------------------------------

### ParallelSotopiaEnv Initialization

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/envs/parallel.md

Demonstrates how to initialize the ParallelSotopiaEnv with custom action types and action order.

```APIDOC
## ParallelSotopiaEnv

### Description
Initializes the parallel environment for agents.

### Parameters
- `available_action_types` (set[ActionType], optional): The action types available to the agents. Defaults to `{"none", "speak", "non-verbal communication", "action", "leave"}`.
- `action_order` (Literal["simultaneous", "round-robin", "random"], optional): How agents take actions. Defaults to `"simultaneous"`.
- `model_name` (str, optional): Name of the language model. Defaults to `"gpt-3.5-turbo"`.
- `evaluators` (list[Evaluator], optional): List of evaluators for responses. Defaults to `[]`.
- `terminal_evaluators` (list[Evaluator], optional): List of evaluators for terminal states. Defaults to `[]`.
- `uuid_str` (str | None, optional): UUID to load the environment profile from the database.
- `env_profile` (EnvironmentProfile | None, optional): Profile of the environment.
- `background_class` (Optional[Type[TBackground]], optional): Class for background scenarios, defaults to `ScriptBackground`.

### Usage Example
```python
env = ParallelSotopiaEnv(
    available_action_types={"none", "speak", "action"},
    action_order="round-robin",
    model_name="gpt-3.5-turbo"
)
```
```

--------------------------------

### Example PR Titles

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/contribution/contribution.md

Examples of valid Pull Request titles following conventional commit standards.

```text
refactor: modify package path
```

```text
feat(frontend): xxxx
```

--------------------------------

### Install Sotopia with Conda

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/index.mdx

Create a new conda environment named 'sotopia' with Python 3.11 and activate it before installing the package.

```bash
conda create -n sotopia python=3.11;
conda activate sotopia;
```

--------------------------------

### Deploy Sotopia API Server with Modal

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/examples/deployment.md

Run this command from the `sotopia/sotopia/ui` directory to deploy the Sotopia Python API server to Modal.

```bash
modal deploy sotopia/ui/modal_api_server.py
```

--------------------------------

### Example Output Messages

Source: https://github.com/sotopia-lab/sotopia/blob/main/examples/experimental/tick_and_echo_agents/readme.md

Illustrates the expected JSON output messages generated during the execution of the tick and echo agents example. This includes timestamps, channel information, and message data.

```json
{"timestamp":"2024-10-14T15:23:53.876886","channel":"tick/secs/1","data":{"data_type":"tick","tick":0}}
{"timestamp":"2024-10-14T15:23:53.878931","channel":"tick","data":{"data_type":"text","text":"Tick 0"}}
{"timestamp":"2024-10-14T15:23:53.882522","channel":"echo_tick","data":{"data_type":"text","text":"Hello, Tick 0!"}}
{"timestamp":"2024-10-14T15:23:54.878441","channel":"tick/secs/1","data":{"data_type":"tick","tick":1}}
{"timestamp":"2024-10-14T15:23:54.880346","channel":"tick","data":{"data_type":"text","text":"Tick 1"}}
{"timestamp":"2024-10-14T15:23:54.881737","channel":"echo_tick","data":{"data_type":"text","text":"Hello, Tick 1!"}}
```

--------------------------------

### Initialize Redis Connection and Import Models

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/redis_stats.ipynb

Sets up the environment for interacting with Redis by configuring the connection URL and importing necessary data models.

```python
import os
import sys
import rich
from collections import Counter
from sotopia.database.persistent_profile import (
    AgentProfile,
    EnvironmentProfile,
    RelationshipProfile,
)
from sotopia.database.logs import EpisodeLog
from sotopia.database.env_agent_combo_storage import EnvAgentComboStorage

sys.path.append("../")
os.environ["REDIS_OM_URL"] = "redis://:QzmCUD3C3RdsR@localhost:6379"
```

--------------------------------

### Get All Agents

Source: https://github.com/sotopia-lab/sotopia/blob/main/sotopia/api/README.md

Retrieves a list of all available agents.

```APIDOC
## GET /agents

### Description
Get all agents.

### Method
GET

### Endpoint
/agents

### Response
#### Success Response (200)
- agents (list[AgentProfile]) - A list of agent profiles.
```

--------------------------------

### Get All Scenarios

Source: https://github.com/sotopia-lab/sotopia/blob/main/sotopia/api/README.md

Retrieves a list of all available scenarios.

```APIDOC
## GET /scenarios

### Description
Get all scenarios.

### Method
GET

### Endpoint
/scenarios

### Response
#### Success Response (200)
- scenarios (list[EnvironmentProfile]) - A list of environment profiles.
```

--------------------------------

### Download and Launch Redis Server

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/tutorials/1.2-browse-data.ipynb

Downloads the Sotopia dataset dump file and launches the Redis server in the background. Ensure the Redis server is running before proceeding to interact with the data.

```bash
%%capture
# @title Download existing data in a single file, and launch redis

!mkdir -p /content/redis-stack-server-7.2.0-v10/var/db/redis-stack
!curl -L https://huggingface.co/datasets/cmu-lti/sotopia-pi/resolve/main/dump.rdb?download=true --output /content/redis-stack-server-7.2.0-v10/var/db/redis-stack/dump.rdb
!./redis-stack-server-7.2.0-v10/bin/redis-stack-server --daemonize yes
```

--------------------------------

### Get All Scenarios

Source: https://github.com/sotopia-lab/sotopia/blob/main/sotopia/api/README.md

Retrieves a list of all available simulation scenarios.

```APIDOC
## GET /scenarios

### Description
Fetches a list of all available scenarios that can be used to configure simulations.

### Method
GET

### Endpoint
`/scenarios`

### Response
#### Success Response (200)
- **scenarios** (Array) - A list of available scenario objects.
```

--------------------------------

### Get All Agents

Source: https://github.com/sotopia-lab/sotopia/blob/main/sotopia/api/README.md

Retrieves a list of all available agents that can participate in simulations.

```APIDOC
## GET /agents

### Description
Fetches a list of all available agents that can be used in simulations.

### Method
GET

### Endpoint
`/agents`

### Response
#### Success Response (200)
- **agents** (Array) - A list of available agent objects.
```

--------------------------------

### Creating a Custom Agent: HelloWorldAgent

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/concepts/agents.md

Example of creating a custom agent by subclassing BaseAgent and implementing the aact method. This agent always responds with 'Hello, world!'. Ensure necessary imports from sotopia.agents and sotopia.messages.

```python
from sotopia.agents.base_agent import BaseAgent
from sotopia.messages.message_classes import AgentAction, Observation

class HelloWorldAgent(BaseAgent):
    async def aact(self, observation: Observation) -> AgentAction:
        return AgentAction(action_type="speak", argument="Hello, world!")
```

--------------------------------

### Run Sotopia Web Interface Server

Source: https://github.com/sotopia-lab/sotopia/blob/main/examples/experimental/sotopia_original_replica/readme.md

Launch the FastAPI server for the Sotopia web interface on port 8080.

```bash
fastapi run sotopia/api/fastapi_server.py --port 8080
```

--------------------------------

### Stop Redis Server

Source: https://github.com/sotopia-lab/sotopia/blob/main/scripts/README.md

Stops the Redis server that was started by the `start_redis_with_dump.sh` script.

```bash
./scripts/stop_redis.sh
```

--------------------------------

### Sample EnvAgentComboStorage and Serialize to JSON

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/redis_stats.ipynb

Demonstrates sampling EnvAgentComboStorage using EnvironmentList, specifically focusing on 'hard' environments, and preparing a list for benchmarking.

```python
from sotopia.samplers import ConstraintBasedSampler
from sotopia.messages import AgentAction, Observation
from sotopia.agents import LLMAgent
import json
# In this example, we will demonstrate using the EnvironmentList class to sample a list of EnvAgentComboStorage and serialize it to a json file that can be used for sharing with others for benchmarking purposes.


def _sample_env_agent_combo_and_push_to_db(env_id: str) -> list[EnvAgentComboStorage]:
    combo_list = []
    sampler = ConstraintBasedSampler[Observation, AgentAction](env_candidates=[env_id])
    env_agent_combo_list = list(
        sampler.sample(agent_classes=[LLMAgent] * 2, replacement=False, size=10)
    )
    for env, agent in env_agent_combo_list:
        combo = EnvAgentComboStorage(
            env_id=env.profile.pk,
            agent_ids=[agent[0].profile.pk, agent[1].profile.pk],
        )
        combo_list.append(combo)
    return combo_list


# First we will extrat the hard environments from the EnvironmentList
hard_envs = EnvironmentList.get("01HAK34YPB1H1RWXQDASDKHSNS").environments
print(len(hard_envs))
hard_envs_set = set(hard_envs)

# Next we will sample 10 EnvAgentComboStorage from each hard environment
final_list_for_benchmark_agents = []
for env in hard_envs_set:
    combo_list = EnvAgentComboStorage.find(EnvAgentComboStorage.env_id == env).all()
    print(len(combo_list))
    final_list_for_benchmark_agents.extend(combo_list)
```

--------------------------------

### Get Episodes by ID or Tag

Source: https://github.com/sotopia-lab/sotopia/blob/main/sotopia/api/README.md

Retrieves episodes based on their ID or a specified tag.

```APIDOC
## GET /episodes/?get_by={id|tag}/{episode_id|episode_tag}

### Description
Get episode by episode_tag.

### Method
GET

### Endpoint
/episodes/

### Parameters
#### Query Parameters
- **get_by** (Literal["id", "tag"]) - Required - Specifies whether to retrieve by ID or tag.
- **episode_id** (str) or **episode_tag** (str) - Required - The ID or tag of the episode to retrieve.

### Response
#### Success Response (200)
- episodes (list[Episode]) - A list of episodes matching the criteria.
```

--------------------------------

### Run Minimalist Demo Script

Source: https://github.com/sotopia-lab/sotopia/blob/main/README.md

Executes a minimalist demonstration script for Sotopia. This is a command-line operation.

```bash
python examples/minimalist_demo.py
```

--------------------------------

### Get Scenarios by ID or Tag

Source: https://github.com/sotopia-lab/sotopia/blob/main/sotopia/api/README.md

Retrieves scenarios based on their ID or a specified tag.

```APIDOC
## GET /scenarios/?get_by={id|tag}/{scenario_id|scenario_tag}

### Description
Get scenarios by scenario_tag.

### Method
GET

### Endpoint
/scenarios/

### Parameters
#### Query Parameters
- **get_by** (Literal["id", "tag"]) - Required - Specifies whether to retrieve by ID or tag.
- **scenario_id** (str) or **scenario_tag** (str) - Required - The ID or tag of the scenario to retrieve.

### Response
#### Success Response (200)
- scenarios (list[EnvironmentProfile]) - A list of environment profiles matching the criteria.
```

--------------------------------

### Get Agents by ID, Gender, or Occupation

Source: https://github.com/sotopia-lab/sotopia/blob/main/sotopia/api/README.md

Retrieves agents based on their ID, gender, or occupation.

```APIDOC
## GET /agents/?get_by={id|gender|occupation}/{value}

### Description
Get agents by id, gender, or occupation.

### Method
GET

### Endpoint
/agents/

### Parameters
#### Query Parameters
- **get_by** (Literal["id", "gender", "occupation"]) - Required - Specifies the attribute to filter agents by.
- **value** (str) - Required - The value of the agent attribute to filter by (e.g., agent_id, agent_gender, or agent_occupation).

### Response
#### Success Response (200)
- agents (list[AgentProfile]) - A list of agent profiles matching the criteria.
```

--------------------------------

### Get Model Pair Keys

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/figure_plots.ipynb

Retrieves the keys (model pairs) from the aggregated performance data.

```python
model_pair2performance.keys()
```

--------------------------------

### Get All EnvironmentList Primary Keys

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/redis_stats.ipynb

Retrieves and prints the total number of primary keys for the EnvironmentList.

```python
from sotopia.database.persistent_profile import EnvironmentList

all_list = EnvironmentList.all_pks()
all_list = list(all_list)
print(len(all_list))
```

--------------------------------

### Create Sotopia .env Configuration File

Source: https://github.com/sotopia-lab/sotopia/blob/main/README.md

Creates a .env file to configure Sotopia, including the required OpenAI API key and the storage backend. The Redis connection URL is optional if using Redis.

```bash
# Create a .env file
cat > .env << EOF
# Required: OpenAI API key
OPENAI_API_KEY=your_openai_key_here

# Storage backend: "redis" (default) or "local"
SOTOPIA_STORAGE_BACKEND=local

# Redis connection (only needed if using Redis backend)
# REDIS_OM_URL=redis://localhost:6379
EOF
```

--------------------------------

### Get Specific Environment Profile

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/redis_stats.ipynb

Retrieves and prints a specific EnvironmentProfile using its primary key.

```python
# get a specific environment profile
env_profile_id = all_envs[0]
env = EnvironmentProfile.get(env_profile_id)
rich.print(env)
```

--------------------------------

### Get All Agent Primary Keys

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/redis_stats.ipynb

Retrieves and prints the total number of primary keys available for AgentProfile.

```python
agent_pks = AgentProfile.all_pks()
agent_pks = list(agent_pks)
print(len(agent_pks))
```

--------------------------------

### Sample environment and agents with constraints

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/samplers/constraint_based_sampler.md

Use this method to sample environments and agents according to environment constraints. Specify agent classes, number of agents, sampling with or without replacement, sample size, and parameters for environments and agents.

```python
from sotopia.agents.some_agent import SomeAgent
from sotopia.samplers.constraint_based_sampler import ConstraintBasedSampler

sampler = ConstraintBasedSampler()
for env, agents in sampler.sample(
    agent_classes=SomeAgent,
    n_agent=2,
    replacement=True,
    size=3,
    env_params={},
    agents_params=[{}, {}]
):
    # Use the `env` and `agents`
    pass
```

--------------------------------

### Set and Get LLMAgent Goal

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/agents/llm_agent.md

Sets and retrieves the goal for an LLMAgent. The goal must be set before it can be retrieved.

```python
llm = LLMAgent()
llm.goal = "Write a poem about nature"
```

--------------------------------

### Reset ParallelSotopiaEnv Episode

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/envs/parallel.md

Example of resetting the environment for a new episode, specifying seed, agents, and omniscient mode.

```python
observations = env.reset(
    seed=42,
    agents=agents,
    omniscient=True
)
```

--------------------------------

### Create and Configure an LLMAgent

Source: https://context7.com/sotopia-lab/sotopia/llms.txt

Instantiate an `LLMAgent` using an `AgentProfile` and a LiteLLM-compatible model. The agent can automatically generate goals or have them pre-set. Control script-like behavior and action constraint strictness.

```python
from sotopia.agents import LLMAgent
from sotopia.database import AgentProfile

profile = AgentProfile(
    first_name="Lena", last_name="Koch",
    age=35, occupation="Lawyer",
    gender="Woman", gender_pronoun="She/her",
    public_info="Partner at a mid-size firm",
    personality_and_values="Highly analytical, values fairness",
    secret="Considers leaving law for writing",
)
profile.save()

agent = LLMAgent(
    agent_profile=profile,
    model_name="gpt-4o",
    script_like=False,            # True = generate a scripted turn rather than react
    strict_action_constraint=False,
    custom_template=None,         # optional Jinja-style template override
)
agent.goal = "Negotiate a fair settlement for your client"

```

--------------------------------

### Run Duskmire Werewolves Game

Source: https://github.com/sotopia-lab/sotopia/blob/main/examples/experimental/werewolves/README.md

Execute the main script to start the game. Ensure your Redis server is running.

```bash
python examples/experimental/werewolves/main.py
```

--------------------------------

### Instantiate and Use BaseRenderer

Source: https://github.com/sotopia-lab/sotopia/blob/main/docs/pages/python_API/renderers/base.md

Shows how to create a BaseRenderer instance and use it to render a string with a given context. The BaseRenderer currently returns the input string unmodified.

```python
context = RenderContext(viewer="human", verbose=False, tags_to_render=["highlight"])
renderer = BaseRenderer()
rendered_string = renderer("This is a test string.", context)
print(rendered_string)  # Output: This is a test string.
```

--------------------------------

### Get All Environment Profile IDs

Source: https://github.com/sotopia-lab/sotopia/blob/main/notebooks/redis_stats.ipynb

Retrieves and prints the count and the first five primary keys of all EnvironmentProfile entries.

```python
# get all environments
all_envs = list(EnvironmentProfile.all_pks())
print(len(all_envs))
print(all_envs[:5])
```

--------------------------------

### Configure Sotopia Storage Backend

Source: https://github.com/sotopia-lab/sotopia/blob/main/README.md

Sets the storage backend for Sotopia. 'redis' is recommended for production, while 'local' is simpler for development. Redis requires a running Redis server.

```bash
export SOTOPIA_STORAGE_BACKEND=redis
```

```bash
export SOTOPIA_STORAGE_BACKEND=local
```

--------------------------------

### Get All Agents API

Source: https://github.com/sotopia-lab/sotopia/blob/main/sotopia/api/README.md

Use this endpoint to retrieve a list of all available agents. This is useful for selecting agents to participate in a simulation.

```bash
curl -X GET "http://localhost:8000/agents"
```