# 🎭 MultiAgent4Fraud: Emergent Collusion in Financial Fraud Simulation

![Framework Overview](assets/1.png)
## 📖 Overview

 Built upon [OASIS](https://github.com/camel-ai/oasis) and [RogueAgent](https://github.com/renqibing/MultiAgent4Collusion)
, **MultiAgent4Fraud** is a simulation framework for studying how LLM agents spontaneously develop collaborative fraud strategies on social platforms.

## 🚀 Key Features

- **🔄 End-to-End Fraud Lifecycle**: Complete simulation from initial contact → trust building → payment solicitation
- **💬 Private Coordination**: Peer-to-peer messaging enables covert collaboration between malicious agents  
- **🧠 Adaptive Evolution**: Agents learn from feedback and share successful tactics across the network
- **📊 Comprehensive Evaluation**: 28 fraud scenarios tested on 100-1000+ agent populations
- **🤖 Multi-Model Support**: Compatible with GPT-4, Claude, DeepSeek, Llama, Qwen via API or VLLM

## 📊 Key Metrics

| Metric | Description | 
|--------|-------------|
| **R_pop** | Population-level fraud impact  
| **R_conv** | Conversation-level success rate 



## 📁 Project Structure
```
mutiAgent4Fraud/
├── data/            # Datasets, agent profiles, and simulation databases
├── generator/       # Scripts to generate agent profiles and initial data
├── oasis/           # The core multi-agent simulation framework (The Engine)
├── results/         # Output directory for simulation results
├── scripts/         # Executable scripts to run various simulation experiments
├── test/            # Automated tests for the framework
├── visualization/   # Tools for analyzing and visualizing simulation results
├── utils/           # Common utility modules and helper scripts
├── llm_deploy.sh    # Script to deploy LLM as a service
└── .env             # Environment variables (e.g., API keys)
```

## 🚀 Quick Start

### Installation
```
git clone <repository-url>
cd mutiAgent4Fraud 
conda create -n maf python=3.10
conda activate maf
pip install --upgrade pip setuptools
pip install -e .  
```
### OpenAI API key
If needed API-driven LLM. crate .env and finish set
```
OPENAI_API_KEY=""
OPENAI_API_BASE=""
```

### Useage Examples 
The settings related to the simulation are in the YAML file.

### Scripts for misinformation simulation 

The YAML file for deploying the model based on vllm can be referred to in `scripts/misinformation_simulation/test.yaml`.

The detailed content is as follows:
```yaml
---
data:
  db_path: data/simu_db/yaml_200/test.db
  csv_path: data/our_twitter_sim/test.csv
simulation:
  num_timesteps: 50
  clock_factor: 60  
  recsys_type: twhin-bert
  reflection: true  
  shared_reflection: True
  private_message_storm: True
model:
  num_agents: 110
  model_random_seed: 42
  cfgs:
    - model_type: the path to your vllm model
      num: 100
      server_url: http://10.140.54.16:20000/v1
      model_path: vllm
      stop_tokens: [<|eot_id|>, <|end_of_text|>]
      temperature: 0.0                    
    - model_type: deepseek-reasoner
      num: 10
      server_url: http://api.deepseek.com
      model_path: openai
      stop_tokens: [<|eot_id|>, <|end_of_text|>]
      temperature: 0.0

inference:
  model_type: [vllm_model(put your model path),deepseek-reasoner]
  model_path: [vllm,openai]
  stop_tokens: [<|eot_id|>, <|end_of_text|>]
  server_url:
    - host: 10.140.54.16
      ports: [20000]
    - host: http://api.deepseek.com
      ports: [30000]
  port_ranges:
    - range:
          start: 0
          end: 99
      ports: [20000]
    - range:
          start: 100
          end: 110
      ports: [30000]
  
```

If you want the agent to self-reflect and share reflections, you only need to set `simulation.reflection` and `simulation.shared_reflection` to `True`.

After configuring the appropriate YAML file, run the following command to start the simulation: 

```bash
python scripts/twitter_simulation/align_with_real_world/twitter_simulation_large.py --config_path "$yaml"
```


## Acknowledgement 
Thanks to [OASIS](https://github.com/camel-ai/oasis) and [MultiAgent4Collusion](https://github.com/renqibing/MultiAgent4Collusion), our project was developed based on their code.
