OASIS Social Simulation
Simulate large-scale social-media behavior with LLM-driven users.
- Source repo
- camel-ai/oasis
- Stars
- ★ 5.4k
- Last updated
- 3d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 25/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A computational-social-science researcher studying information diffusion, polarization, or herd behavior in a Reddit-style setting can run experiments with profile-based populations.
- Not a fit if
- Users who want a turnkey app; you must supply profile JSON and database files
- Projects needing multimodal platforms, which are still an open feature request
- Source review
- 25/100 · Major gaps 8 safety controls not found
What does this agent do, and when should you use it?
OASIS is an open-source social-media simulator for Twitter- and Reddit-like environments, designed to model up to one million LLM-powered users. A simulation is assembled from an agent graph, a platform selection, and a database path, then advanced through asynchronous reset and step calls. Agents can perform social operations including follows, posts, comments, reposts, searches, and mutes; the project states that it supports 23 actions. Interest-based and hot-score-based recommendation algorithms model how users discover and engage with content. Simulation data is written to the configured database file for subsequent experiment analysis and visualization.
The workflow starts with generate_reddit_agent_graph(profile_path, model, available_actions), which creates a Reddit agent graph from a user-profile JSON file such as ./data/reddit/user_data_36.json. It then creates an environment with oasis.make(agent_graph=..., platform=oasis.DefaultPlatformType.REDDIT, database_path=...) and initializes it through await env.reset(). Each timestep is submitted through await env.step(actions), using per-agent ManualAction values or LLMAction values; CREATE_POST and CREATE_COMMENT, for example, accept content and a post_id where applicable. The supplied example creates its model through CAMEL's ModelFactory.create with ModelPlatformType.OPENAI and ModelType.GPT_4O_MINI, then closes the environment with await env.close().
- A computational-social-science researcher studying information diffusion, polarization, or herd behavior in a Reddit-style setting can run experiments with profile-based populations.
- A recommendation-systems researcher can examine how interest-based versus hot-score-based discovery changes content interaction in a social simulation.
- An experiment team that needs a prescribed interaction sequence can use
ManualActionto control posts, comments, follows, and searches. - A researcher testing autonomous social behavior can assign
LLMAction()to agents and let the configured model produce their actions. - A user preparing post-simulation analysis can write results to a chosen database path and continue with the project's user-generation and visualization tutorial.
How do you install or deploy this agent?
Python, network access, and an OpenAI API key are required for the documented quick start. Install and configure the key:
pip install camel-oasis
export OPENAI_API_KEY=<insert your OpenAI API key>Then prepare a profile file; the example uses ./data/reddit/user_data_36.json.
How do you use this agent?
In an async Python program, create a model with ModelFactory.create(model_platform=ModelPlatformType.OPENAI, model_type=ModelType.GPT_4O_MINI), then build a graph with generate_reddit_agent_graph(...). Create the environment using oasis.make(..., platform=oasis.DefaultPlatformType.REDDIT, database_path='./data/reddit_simulation.db'). After await env.reset(), submit actions such as ManualAction(action_type=ActionType.CREATE_POST, action_args={'content': 'Hello, world!'}), or assign LLMAction() to agents, through await env.step(actions). Finish with await env.close().
What are this agent's strengths and limitations?
- The project explicitly targets social simulations with up to one million agents.
- It supports both controlled
ManualActioninputs and model-drivenLLMActionbehavior, enabling controlled and autonomous experimental designs. - Interest-based and hot-score-based recommendation systems are included rather than leaving content discovery outside the simulation.
- The environment has a clear execution boundary: agent graph, platform type, database path, and async
reset/steplifecycle.
- The documented quick start depends on an OpenAI API key and CAMEL's OpenAI model configuration, so model calls incur provider cost.
- The provided cost reference covers only a QWEN_TURBO configuration; actual usage varies with agent count, activation probability, and timesteps.
- The supplied example documents Reddit and a local profile JSON path, but does not detail complete configuration flows for other platforms.
- Users must manage local profile and database files; the example deletes an existing database file before running.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| OASIS Social Simulation This agent | 25 · Major gaps | Library / SDKFree + model costs | ★ 5.4k | 3d ago | Python | OpenAI API |
| ALTA Research Trading Workbench | 83 · Good | Web app | ★ 1.1k | 1mo ago | Python | — |
| CAMEL Multi-Agent Framework | 61 · Some gaps | Library / SDKFree + model costs | ★ 18k | 4d ago | Python | OpenAI API |
| Station Research Environment | 60 · Some gaps | CLIFree + model costs | ★ 211 | 23d ago | Python | — |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows no documentation on permission management, user confirmation, data flow transparency, sensitive data handling, dependency security, external effects, rollback, or source attribution. No malicious behavior found, but security design is absent. Hence all trust criteria score 0.
Self-consistency: Version numbers in README and pyproject.toml are consistent (0.2.5), but README update date (2025-12-04) mismatches pyproject version, minor inconsistency. Dependency availability: Dependencies listed in pyproject.toml, but no lock file or compatibility notes. Failure messages: No documentation on error handling or user prompts.
Audience and scenarios: README clearly targets researchers and developers, provides simulation scenarios. Capability boundaries: Describes 23 actions and recommendation systems, but no explicit limits. Trigger precision: No trigger mechanisms or precise control. Environment fit: Installation and configuration instructions provided, but no OS or hardware requirements.
Information architecture: README well-structured with quick start, features, tutorials. Install notes: pip install and API key setup provided. Naming stability: Version number exists, but changelog incomplete. Examples and FAQ: Code examples and tutorial links provided, but no FAQ. Known limitations: Not mentioned. License: Apache 2.0, file present. Versioning and changelog: Update log present but no full version history. Maintenance responsibility: No explicit maintainer specified.
Output usability: Tutorials for visualizing simulation results provided, but output format not specified. Marginal value: Large-scale simulation capability offers research value. Cost-benefit: Token consumption reference provided, but no detailed cost analysis.
Claim traceability: README cites paper and dataset, but no detailed verification. Cross-source corroboration: Paper and dataset links exist, but no independent verification. Fact-inference separation: No clear distinction between facts and inferences.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- No security design documentation, including permission management, data flow transparency, and sensitive data handling.
- Dependencies are not pinned, potentially introducing supply chain risks.
- README update date mismatches version number, affecting version tracking.
- No known limitations or failure handling documentation, users may encounter unexpected errors.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Update camel-ai to version 0.2.90. What's Changed * update qr code by @Doudou-Wu in https://github.com/camel-ai/oasis/pull/191 * update qr code by @Doudou-Wu in https://github.com/camel-ai/oasis/pull/192 * update qr code by @Doudou-Wu in https://github.com/camel-ai/oasis/pull/193 * update qr code by @Doudou-Wu in https://github.com/camel-ai/oasis/pull/194 * update qr code by @Doudou-Wu in https://github.com/camel-ai/oasis/pull/195 * update qr code by @Doudou-Wu in https://github.com/camel-ai/oasis/pull/196 * update qr code by @Doudou-Wu in https://github.com/camel-ai/oasis/pull/199 …View on GitHub ↗ -
Release notes excerpt
Update camel-ai to version 0.2.78. What's Changed * feat: Add Docker and Docker Compose Support by @JoyceXu02 in https://github.com/camel-ai/oasis/pull/140 * Fixes:#131 follows_env_template by @Raysin-cn in https://github.com/camel-ai/oasis/pull/147 * Upgarde camel-ai to 0.2.70 and fix #113 by @zhangzaibin in https://github.com/camel-ai/oasis/pull/149 * feat: Update the Cookbook in the Docs and use the ModelManager #134 by @DiligenceLai in https://github.com/camel-ai/oasis/pull/155 …View on GitHub ↗
FAQ
How many tokens can a simulation consume?
Must I use OpenAI?
OPENAI_API_KEY, ModelPlatformType.OPENAI, and GPT_4O_MINI. The update notes say that each agent's models, tools, and prompts can be customized, but the supplied material does not provide configuration steps for another provider.Can I prescribe an agent's behavior exactly?
ManualAction lets you specify an action type and arguments, such as creating a post or comment. You can instead assign LLMAction() when you want the model to produce actions.Where are simulation results stored?
database_path. The example uses ./data/reddit_simulation.db and removes an existing file at that path before execution.