OASIS Social Simulation
Simulate large-scale social-media behavior with LLM-driven users.
Per-dimension scores and reasoning
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.
- 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.
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.
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 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().
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.