> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oasis.camel-ai.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Start using OASIS for social simulations in under 5 minutes
## Setup your environment
Learn how to set up OASIS and run your first social simulation.
### Installation
You can install OASIS in two ways:
```bash theme={null}
pip install camel-oasis
```
```bash theme={null}
git clone https://github.com/camel-ai/oasis.git
cd oasis
pip install --upgrade pip setuptools
pip install -e . # This will install dependencies as specified in pyproject.toml
```
## Running simulations
OASIS supports different types of LLM backends for running simulations. Choose the option that works best for your needs.
### Using OpenAI API
Add your OpenAI API key to your environment variables:
**For Bash (Linux, macOS, Git Bash on Windows):**
```bash theme={null}
export OPENAI_API_KEY=
export OPENAI_API_BASE_URL= # Optional: for proxy services
```
**For Windows Command Prompt:**
```bash theme={null}
set OPENAI_API_KEY=
set OPENAI_API_BASE_URL= # Optional: for proxy services
```
**For Windows PowerShell:**
```bash theme={null}
$env:OPENAI_API_KEY=""
$env:OPENAI_API_BASE_URL="" # Optional: for proxy services
```
If you install with `pip`, download [this file](https://github.com/camel-ai/oasis/blob/main/data/reddit/user_data_36.json) to your own `./data/reddit/user_data_36.json` directory.
Execute the Reddit simulation script:
```python theme={null}
import asyncio
import os
from camel.models import ModelFactory
from camel.types import ModelPlatformType, ModelType
import oasis
from oasis import (ActionType, LLMAction, ManualAction,
generate_reddit_agent_graph)
async def main():
# Define the model for the agents
openai_model = ModelFactory.create(
model_platform=ModelPlatformType.OPENAI,
model_type=ModelType.GPT_4O_MINI,
)
# Define the available actions for the agents
available_actions = [
ActionType.LIKE_POST,
ActionType.DISLIKE_POST,
ActionType.CREATE_POST,
ActionType.CREATE_COMMENT,
ActionType.LIKE_COMMENT,
ActionType.DISLIKE_COMMENT,
ActionType.SEARCH_POSTS,
ActionType.SEARCH_USER,
ActionType.TREND,
ActionType.REFRESH,
ActionType.DO_NOTHING,
ActionType.FOLLOW,
ActionType.MUTE,
]
agent_graph = await generate_reddit_agent_graph(
profile_path="./data/reddit/user_data_36.json",
model=openai_model,
available_actions=available_actions,
)
# Define the path to the database
db_path = "./data/reddit_simulation.db"
# Delete the old database
if os.path.exists(db_path):
os.remove(db_path)
# Make the environment
env = oasis.make(
agent_graph=agent_graph,
platform=oasis.DefaultPlatformType.REDDIT,
database_path=db_path,
)
# Run the environment
await env.reset()
actions_1 = {}
actions_1[env.agent_graph.get_agent(0)] = [
ManualAction(action_type=ActionType.CREATE_POST,
action_args={"content": "Hello, world!"}),
ManualAction(action_type=ActionType.CREATE_COMMENT,
action_args={
"post_id": "1",
"content": "Welcome to the OASIS World!"
})
]
actions_1[env.agent_graph.get_agent(1)] = ManualAction(
action_type=ActionType.CREATE_COMMENT,
action_args={
"post_id": "1",
"content": "I like the OASIS world."
})
await env.step(actions_1)
actions_2 = {
agent: LLMAction()
for _, agent in env.agent_graph.get_agents()
}
# Perform the actions
await env.step(actions_2)
# Close the environment
await env.close()
if __name__ == "__main__":
asyncio.run(main())
```
This will start a simulation of user interactions in a Reddit-like environment.
### Using local open-source models with VLLM
1. Install VLLM by following the instructions in the [VLLM repository](https://github.com/vllm-project/vllm)
2. Download a model (e.g., Qwen 2.5) to your local machine:
```bash theme={null}
pip install huggingface_hub
huggingface-cli download --resume-download "Qwen/Qwen2.5-7B-Instruct" \
--local-dir "YOUR_LOCAL_MODEL_DIRECTORY" \
--local-dir-use-symlinks False \
--resume-download \
--token "YOUR_HUGGING_FACE_TOKEN"
```
3. Deploy the VLLM API server:
```bash theme={null}
vllm serve /path/to/Qwen2.5-7B-Instruct --host 0.0.0.0 --port 8000 \
--served-model-name 'qwen-2' \
--enable-auto-tool-choice \
--tool-call-parser hermes
```
4. Test if VLLM is correctly deployed:
```bash theme={null}
curl http://$ip:$port/v1/models
```
1. Edit or write the `scripts/environment/twitter_simulation.py` file to use your VLLM deployment:
```python theme={null}
vllm_model_1 = ModelFactory.create(
model_platform=ModelPlatformType.VLLM,
model_type="qwen-2",
url="http://$ip:$port",
)
vllm_model_2 = ModelFactory.create(
model_platform=ModelPlatformType.VLLM,
model_type="qwen-2",
url="http://$ip:$port",
)
models = [vllm_model_1, vllm_model_2]
```
2. Prepare the user profiles:
If you install with `pip`, download [this file](https://github.com/camel-ai/oasis/blob/refactor/data/twitter_dataset/anonymous_topic_200_1h/False_Business_0.csv) to your own `data/twitter_dataset/anonymous_topic_200_1h/False_Business_0.csv` directory.
3. Run the Twitter simulation:
```python theme={null}
import asyncio
import os
from camel.models import ModelFactory
from camel.types import ModelPlatformType
import oasis
from oasis import (ActionType, LLMAction, ManualAction,
generate_twitter_agent_graph)
async def main():
# Define the models for agents. Agents will select models based on
# pre-defined scheduling strategies
vllm_model_1 = ModelFactory.create(
model_platform=ModelPlatformType.VLLM,
model_type="qwen-2",
url="http://$ip:$port",
)
vllm_model_2 = ModelFactory.create(
model_platform=ModelPlatformType.VLLM,
model_type="qwen-2",
url="http://$ip:$port",
)
models = [vllm_model_1, vllm_model_2]
# Define the available actions for the agents
available_actions = [
ActionType.CREATE_POST,
ActionType.LIKE_POST,
ActionType.REPOST,
ActionType.FOLLOW,
ActionType.DO_NOTHING,
ActionType.QUOTE_POST,
]
agent_graph = await generate_twitter_agent_graph(
profile_path="./data/reddit/user_data_36.json",
model=models,
available_actions=available_actions,
)
# Define the path to the database
db_path = "./data/twitter_simulation.db"
# Delete the old database
if os.path.exists(db_path):
os.remove(db_path)
# Make the environment
env = oasis.make(
agent_graph=agent_graph,
platform=oasis.DefaultPlatformType.TWITTER,
database_path=db_path,
)
# Run the environment
await env.reset()
actions_1 = {}
actions_1[env.agent_graph.get_agent(0)] = ManualAction(
action_type=ActionType.CREATE_POST,
action_args={"content": "Earth is flat."})
await env.step(actions_1)
actions_2 = {
agent: LLMAction()
# Activate 5 agents with id 1, 3, 5, 7, 9
for _, agent in env.agent_graph.get_agents([1, 3, 5, 7, 9])
}
await env.step(actions_2)
actions_3 = {}
actions_3[env.agent_graph.get_agent(1)] = ManualAction(
action_type=ActionType.CREATE_POST,
action_args={"content": "Earth is not flat."})
await env.step(actions_3)
actions_4 = {
agent: LLMAction()
# get all agents
for _, agent in env.agent_graph.get_agents()
}
await env.step(actions_4)
# Close the environment
await env.close()
if __name__ == "__main__":
asyncio.run(main())
```