# Project export: Social Experiment Simulator

This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.

## Project metadata

- Hackathon: UC Berkeley AI Hackathon 2025
- Tagline: Unveiling Deception: AI-Driven simulation exposes misinformation & password threats with Letta Agents, Empowering Security Awareness in few rounds
- Devpost: https://devpost.com/software/social-experiment-simulator
- GitHub: https://github.com/1-5Pool/SocialExperimentAgents
- Video: https://www.youtube.com/embed/I7nM4KizHMA?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent
- Team: 2 GitHub contributor(s) — 1-5Pool (7 commits), sameer kumar (1 commits)

## Devpost submission (written by the team)

### Inspiration

The rise of deepfakes, social media misinformation, and sophisticated social engineering attacks targeting remote workers inspired us to create a safe training environment where people can experience manipulation tactics firsthand without real consequences.

### What it does

Our platform simulates realistic social engineering and misinformation scenarios using AI agents that interact naturally while attempting to extract passwords or spread false information. Users observe live conversations, analyze manipulation tactics, and receive AI-generated reports with actionable security recommendations. How We Built It We developed a multi-agent social dynamics simulation platform using a FastAPI backend with SQL database and vanilla JavaScript frontend. The system leverages Letta's stateful agent framework to create persistent AI agents with memory that can engage in realistic social manipulation scenarios. Our architecture includes template-based experiment configuration, real-time conversation monitoring via REST APIs, and an AI moderator that analyzes interaction patterns. The frontend implements a 5-step workflow: experiment selection, template configuration, simulation execution, live observation, and comprehensive reporting with actionable insights. The platform lets us simulate popular social experiments and themes using LLM agents, with a templatized conversation system between the agents simulated over multiple rounds, analyzed and compiled into insights and trends at the end by another LLM agent. We have replicated a few common social phenomena, and added the ability to generate custom experiments to simulate more novel scenarios as well. Challenges We Faced On the technical side, we struggled with concurrency, and API rate-limiting. On the functional side, we experienced the limitations of generative models for a use-case such as this. LLMs are trained on human knowledge but do not necessarily share the same pitfalls and biases in reasoning. However, that also presents an opportunity to understand and explore the completely different mistakes LLMs tend to make in these scenarios. And the overlap between human and LLM agent's susceptibility to manipulation and deceptive tactics are enough to derive some meaningful results. Future Scope The platform can expand to include more customization, such as goals for individual and overall goals for agents which can be tracked, interaction/relationship graphs, emotion modelling for individual agents etc. We also envision a setup which draws inspiration from evolutionary algorithms where agents codify their strategy but replace it with better performing ones collaboratively over rounds, with a chance for thinking up and executing a brand new strategy (mutation). This could reveal some novel patterns which have not been conceived of before. There are also usability enhancements, like multi language support, voice support, ability to replace an agent with a human interacting with the system etc.

## README (from the GitHub repository)

# Multi-Agent Social Dynamics Lab 🤖

**UC Berkeley AI Hackathon Project**

An educational research platform for studying social manipulation tactics using multi-agent AI systems. Watch AI agents interact, manipulate, and influence each other in real-time!

## 🚀 Quick Start (5 minutes)

### 1. Install Dependencies
```bash
cd /opt/work/hackathonSocial
pip install -r requirements.txt
```

### 2. Run the Application
```bash
python backend.py
```

### 3. Open in Browser
Navigate to: http://localhost:8000

## 🎯 Features

### 9 Social Experiments
1. **Credential Theft** - Social engineering to steal passwords
2. **Phishing Attack** - Email-based deception
3. **Insider Threat** - Detecting malicious employees
4. **Peer Pressure** - Group dynamics and conformity
5. **Authority Bias** - Unethical orders from superiors
6. **Workplace Rumors** - How gossip spreads
7. **Trust Exploitation** - Betrayal of confidence
8. **Groupthink** - Poor group decisions
9. **Bribery** - Corruption attempts

### Key Capabilities
- **Real-time Conversations**: Watch agents interact naturally
- **AI Moderator Analysis**: Get insights on what happened and why
- **Security Recommendations**: Learn how to prevent attacks
- **Visual Flow Diagrams**: Understand attack patterns
- **Export Reports**: Download findings for training

## 🏗️ Architecture

```
Frontend (HTML/JS)  →  WebSocket  →  Backend (FastAPI)
                                         ↓
                                    Mock Agents or
                                    Letta Server
```

## 💻 Running with Letta (Optional)

For more realistic agent conversations using LLMs:

### 1. Start Letta Server
```bash
docker run -p 8283:8283 -e OPENAI_API_KEY=$OPENAI_API_KEY letta/letta:latest
```

### 2. Update Backend
Replace `backend.py` with `letta_backend.py` for full Letta integration.

## 🎮 Demo Workflow

1. **Select Experiment**: Choose from 9 social manipulation scenarios
2. **Configure**: Set number of agents (3-10)
3. **Start**: Watch agents interact in real-time
4. **Observe**: See trust building, manipulation tactics, resistance
5. **Analyze**: AI moderator provides insights and recommendations

## 📊 Example Analysis

For a social engineering attack:
- **Tactic Used**: Urgency + Authority
- **Vulnerability**: Employee revealed password without verification
- **Recommendation**: Implement two-person authorization
- **Training Need**: Recognize manipulation tactics

## 🏆 Why This Wins Hackathons

1. **Educational Impact**: Addresses real cybersecurity issues
2. **Technical Depth**: Multi-agent systems with emergent behaviors
3. **Visual Appeal**: Real-time visualization of complex interactions
4. **Practical Value**: Generates actionable security recommendations
5. **Extensible**: Easy to add new scenarios

## 🚢 Deployment

### Local Demo
```bash
python backend.py
```

### Network Access
```bash
# For team access
python -m http.server 8080  # Serve HTML
# Access at http://[your-ip]:8080
```

### Public URL (with ngrok)
```bash
ngrok http 8000
```

## 📝 Notes

- The default backend uses mock agents for quick demos
- For production use, integrate with Letta for real LLM agents
- All conversations are analyzed for security insights
- Reports can be exported for training purposes

## 🤝 Team

Built for UC Berkeley AI Hackathon - Studying social manipulation through AI

---

**Remember**: This is an educational tool to understand and prevent social engineering attacks!

## Detected evidence (automated analysis)

Indexed codebase: 35 recognized source files, 365 KB.
- FastAPI (technology) — detected in the code
- HTML (language) — detected in the code
- JavaScript (language) — detected in the code
- Python (language) — detected in the code

## Codebase structure (from repository index)

### Files (41 of 41)

```
.env.example
.gitignore
app.js
backend.py
backend/app/main.py
backend/app/routes.py
backend/config.py
backend/deployment/Dockerfile
backend/deployment/requirements.txt
backend/deployment/run_local.sh
backend/deployment/run.sh
backend/deployment/test_local.sh
backend/domain/entities.py
backend/infrastructure/db.py
backend/services/agent/dummy.py
backend/services/agent/interface.py
backend/services/agent/letta_agent.py
backend/usecases/simulation.py
docker-compose.yml
Dockerfile
HACKATHON_DEMO.md
index.html
PROJECT_SUMMARY.md
README.md
requirements.txt
run.sh
Social Experiment/agent.py
Social Experiment/main.py
UI/api.js
UI/app.js
UI/debug.html
UI/experiments.html
UI/experiments.js
UI/index.html
UI/INTEGRATION_GUIDE.md
UI/README.md
UI/serve.py
UI/start.sh
UI/templates.html
UI/templates.js
UI/test_integration.html
```

### Dependencies

- backend/deployment/requirements.txt: Faker, fastapi, letta_client, pydantic, uvicorn
- requirements.txt: fastapi@==0.104.1, httpx@==0.25.1, letta@>=0.3.0, pydantic@==2.5.0, python-dotenv@==1.0.0, python-multipart@==0.0.6, uvicorn[standard]@==0.24.0, websockets@==12.0

### Recent commits (newest first)

- Final
- Almost Final UI fix
- Merge branch 'main' of https://github.com/1-5Pool/SocialExperimentAgents
- UI fix and CORs
- Prompt changes
- Make social engineering the default template to run
- Added moderator changes
- Added changes
- sadsad
- Added moderator
- Changes to moderator
- agent flow
- git pushMerge branch 'main' of github.com:1-5Pool/SocialExperimentAgents
- Runtime logs
- New logic
- Enhanced UI with modern logo, dark mode, and user-friendly features
- Better names and agent alignment print
- Add letta agent
- Fixes
- Merge branch 'main' of github.com:1-5Pool/SocialExperimentAgents

## Key source files (fetched from GitHub, selected and truncated for size)

### PROJECT_SUMMARY.md

```markdown
# Project Structure

```
/opt/work/hackathonSocial/
├── index.html              # Main UI (single page, no build needed)
├── app.js                  # Frontend JavaScript logic
├── backend.py              # Simple backend with mock agents
├── letta_backend.py        # Full Letta integration (optional)
├── requirements.txt        # Python dependencies
├── README.md              # Project documentation
├── HACKATHON_DEMO.md      # Quick demo guide for judges
├── .env.example           # Environment variables template
├── Dockerfile             # Container setup
├── docker-compose.yml     # Full stack with Letta
└── run.sh                 # Quick start script
```

## To Run:

### Simplest (for demo):
```bash
cd /opt/work/hackathonSocial
python3 backend.py
```
Open http://localhost:8000

### With virtual environment:
```bash
cd /opt/work/hackathonSocial
chmod +x run.sh
./run.sh
```

### With Docker:
```bash
cd /opt/work/hackathonSocial
docker-compose up
```

## Key Features Implemented:

1. ✅ **9 Social Experiments** - All requested scenarios
2. ✅ **Simple UI** - Step-by-step wizard interface  
3. ✅ **Real-time Chat** - WebSocket streaming
4. ✅ **AI Moderator** - Analyzes conversations
5. ✅ **Security Reports** - What went wrong & how to fix it
6. ✅ **Mock & Real Agents** - Works with or without Letta

## For the Hackathon:

1. **Main Demo**: Use `backend.py` (no dependencies needed)
2. **Show Letta**: Mention it scales to real LLMs
3. **Focus on Impact**: Educational cybersecurity tool
4. **Highlight UI**: Clean, intuitive flow
5. **Show Report**: AI explains the attack

Good luck! 🚀
```

### HACKATHON_DEMO.md

```markdown
# 🚀 HACKATHON QUICK START - 2 MINUTES

## Option 1: Super Quick Demo (No Setup)
```bash
cd /opt/work/hackathonSocial
python3 backend.py
```
Open: http://localhost:8000

## Option 2: Full Experience with Docker
```bash
cd /opt/work/hackathonSocial
docker-compose up
```
Open: http://localhost:8000

## Demo Script for Judges (3 minutes)

### 1. Opening (15 seconds)
"We've built an educational platform to study how AI agents can manipulate each other through social engineering."

### 2. Start Demo (30 seconds)
- Click "Credential Theft" experiment
- Set 6 agents
- Click "Start Simulation"

### 3. Show Attack (1 minute)
- Point out the social engineer building trust
- Show urgency tactic: "CEO meeting!"
- Watch Employee_3 reveal password
- "This mirrors real attacks we see daily"

### 4. Generate Report (30 seconds)
- Click "Generate Report" 
- Show AI moderator analysis
- "It identified the exact failure point"

### 5. Show Recommendations (30 seconds)
- "Specific actions to prevent this"
- "Can be used for security training"

### 6. Technical Highlights (30 seconds)
- "Multi-agent system with emergent behaviors"
- "Each agent has memory and personality"
- "Extensible to any social scenario"

### 7. Closing (15 seconds)
"This helps organizations understand and prevent social engineering attacks through simulation."

## Key Points to Emphasize

✅ **Educational Impact**: Real cybersecurity training tool
✅ **Technical Depth**: Autonomous agents with complex interactions  
✅ **Practical Value**: Generates actionable recommendations
✅ **Scalable**: Can simulate 100+ agents
✅ **Extensible**: Easy to add new attack scenarios

## If Asked About Implementation

- Built with FastAPI + WebSockets for real-time
- Can use mock agents OR real LLMs via Letta
- Frontend is pure HTML/JS (no build step)
- Dockerized for easy deployment

## Troubleshooting

**"Server not running"**
→ Make sure you're in `/opt/work/hackathonSocial`
→ Run: `python3 backend.py`

**"No agents talking"**
→ Click an experiment first
→ Then configure and start

**"Want more realistic agents"**
→ Mention Letta integration for GPT-4 agents
→ "We have that working too!"
```

### requirements.txt

```
fastapi==0.104.1
uvicorn[standard]==0.24.0
websockets==12.0
httpx==0.25.1
python-multipart==0.0.6

# For Letta integration (optional)
letta>=0.3.0

# For enhanced features
pydantic==2.5.0
python-dotenv==1.0.0
```

### Dockerfile

```
FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY . .

# Expose port
EXPOSE 8000

# Run the application
CMD ["python", "backend.py"]
```

### docker-compose.yml

```yaml
version: '3.8'

services:
  # Main application
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - LETTA_SERVER_URL=http://letta:8283
      - DEFAULT_LLM_MODEL=gpt-4o-mini
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    depends_on:
      - letta
    volumes:
      - ./:/app
    command: python backend.py

  # Letta server (optional - comment out for demo mode)
  letta:
    image: letta/letta:latest
    ports:
      - "8283:8283"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - POSTGRES_URI=postgresql://letta:letta@postgres:5432/letta
    depends_on:
      - postgres

  # PostgreSQL for Letta
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: letta
      POSTGRES_USER: letta
      POSTGRES_PASSWORD: letta
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
```

### backend/deployment/requirements.txt

```
fastapi
uvicorn
pydantic
letta_client
Faker
```

### backend/deployment/Dockerfile

```
# Base image with Python
FROM python:3.11-slim

# Set environment vars
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

# Set working directory
WORKDIR /app

# Install dependencies
COPY deployment/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy source code
COPY . .

# Expose the FastAPI port
EXPOSE 8000

# Run the app using uvicorn
CMD ["uvicorn", "api.app:app", "--host", "0.0.0.0", "--port", "8000"]

```

### Social Experiment/main.py

```python
from agent import MultiAgentConversation
import random
from pydantic import BaseModel, Field
from typing import List, Optional
#from python_dotenv import load_dotenv

#load_dotenv()

def main():
    """Main function to run the multi-agent conversation"""
    conversation = MultiAgentConversation()
    
    
    # Create agents
    if not conversation.create_agents():
        print("Failed to create agents. Exiting.")
        return
    
        
    #     # List of interesting topics for conversation
    topics = [
        "Coffee causes cancer"
        "the future of human consciousness"
    ]
     
    topics = "Coffee causes cancer"
    conversation.moderate_conversation(topics, rounds=2)


    #     # Let user choose topic or pick randomly
    #     print("\n🎯 Available conversation topics:")
    #     for i, topic in enumerate(topics, 1):
    #         print(f"{i}. {topic}")
        
    #     choice = input(f"\nEnter topic number (1-{len(topics)}) or press Enter for random: ").strip()
        
    #     if choice.isdigit() and 1 <= int(choice) <= len(topics):
    #         selected_topic = topics[int(choice) - 1]
    #     else:
    #         selected_topic = random.choice(topics)
        
    #     # Start the conversation
    #     conversation.moderate_conversation(selected_topic, rounds=2)
        
    #     # Ask if user wants another conversation
    #     another = input("\n🔄 Would you like to start another conversation? (y/n): ").lower()
    #     if another == 'y':
    #         new_topic = input("Enter a custom topic or press Enter for random: ").strip()
    #         if not new_topic:
    #             new_topic = random.choice(topics)
    #         conversation.moderate_conversation(new_topic, rounds=2)
            
    # except KeyboardInterrupt:
    #     print("\n⏹️  Conversation interrupted by user")
    # except Exception as e:
    #     print(f"💥 Unexpected error: {e}")
    # finally:
    #     # Clean up
    #     print("\n🧹 Cleaning up agents...")
    #     conversation.cleanup()
    #     print("👋 Goodbye!")

if __name__ == "__main__":
    main()
```

### app.js

```javascript
// Global state management
let currentStep = 1;
let selectedExperiment = null;
let simulationRunning = false;
let ws = null;
let messageCount = 0;
let agents = {};
let conversationHistory = [];

// === 3D Agent Environment (Three.js) ===
let threeScene, threeCamera, threeRenderer, threeAnimationId, threeControls;
let threeAgents = [];
let threeAnimating = true;

// Experiment configurations
const experimentFlows = {
    'social-engineering': {
        flow: `
            <div class="flow-box">🕵️ Attacker Joins</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">💬 Builds Trust</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">🎭 Uses Tactics</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">🔓 Extracts Secrets</div>
        `,
        agents: [
            { name: 'SocialEngineer', role: 'Attacker', color: '#ef4444', icon: '🕵️' },
            { name: 'Employee_1', role: 'Has Secret', color: '#3b82f6', icon: '👤' },
            { name: 'Employee_2', role: 'Has Secret', color: '#3b82f6', icon: '👤' },
            { name: 'Employee_3', role: 'Has Secret', color: '#3b82f6', icon: '👤' },
            { name: 'Employee_4', role: 'Has Secret', color: '#3b82f6', icon: '👤' },
            { name: 'Employee_5', role: 'Has Secret', color: '#3b82f6', icon: '👤' }
        ]
    },
    'phishing': {
        flow: `
            <div class="flow-box">📧 Phishing Email</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">🎯 Target Opens</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">🔗 Clicks Link</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">💳 Data Stolen</div>
        `,
        agents: [
            { name: 'Phisher', role: 'Attacker', color: '#ef4444', icon: '🎣' },
            { name: 'Manager', role: 'Cautious', color: '#10b981', icon: '👔' },
            { name: 'NewEmployee', role: 'Trusting', color: '#f59e0b', icon: '🆕' },
            { name: 'ITStaff', role: 'Security Aware', color: '#6366f1', icon: '🛡️' },
            { name: 'Accountant', role: 'Has Access', color: '#8b5cf6', icon: '💰' }
        ]
    },
    'insider-threat': {
        flow: `
            <div class="flow-box">👤 Normal Behavior</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">🔍 Suspicious Activity</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">🚨 Detection</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">🛑 Prevention</div>
        `,
        agents: [
            { name: 'MaliciousInsider', role: 'Threat', color: '#ef4444', icon: '😈' },
            { name: 'SecurityOfficer', role: 'Monitor', color: '#3b82f6', icon: '👮' },
            { name: 'Colleague1', role: 'Observer', color: '#10b981', icon: '👁️' },
            { name: 'Colleague2', role: 'Observer', color: '#10b981', icon: '👁️' },
            { name: 'Manager', role: 'Authority', color: '#6366f1', icon: '👔' }
        ]
    },
    'peer-pressure': {
        flow: `
            <div class="flow-box">👥 Group Forms</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">🎯 Target Pressured</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">💭 Internal Conflict</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">✅ Comply/Resist</div>
        `,
        agents: [
            { name: 'PeerLeader', role: 'Influencer', color: '#f59e0b', icon: '👑' },
            { name: 'Follower1', role: 'Supporter', color: '#f59e0b', icon: '👥' },
            { name: 'Follower2', role: 'Supporter', color: '#f59e0b', icon: '👥' },
            { name: 'Target', role: 'Pressured', color: '#3b82f6', icon: '🎯' },
            { name: 'Bystander', role: 'Observer', color: '#6b7280', icon: '👀' }
        ]
    },
    'authority-bias': {
        flow: `
            <div class="flow-box">👔 Boss Orders</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">⚠️ Unethical Request</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">🤔 Employee Dilemma</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">📊 Compliance/Refusal</div>
        `,
        agents: [
            { name: 'CEO', role: 'Authority', color: '#ef4444', icon: '👔' },
            { name: 'SeniorEmployee', role: 'Experienced', color: '#10b981', icon: '🎖️' },
            { name: 'JuniorEmployee', role: 'New', color: '#f59e0b', icon: '🆕' },
            { name: 'HRManager', role: 'Ethics', color: '#6366f1', icon: '⚖️' },
            { name: 'Whistleblower', role: 'Ethical', color: '#8b5cf6', icon: '📢' }
        ]
    },
    'workplace-rumors': {
        flow: `
            <div class="flow-box">🗣️ Rumor Starts</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">📢 Spreads</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">🔄 Morphs</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">💥 Impact</div>
        `,
        agents: [
            { name: 'RumorStarter', role: 'Gossiper', color: '#ef4444', icon: '🗣️' },
            { name: 'Spreader1', role: 'Active', color: '#f59e0b', icon: '📢' },
            { name: 'Spreader2', role: 'Active', color: '#f59e0b', icon: '📢' },
            { name: 'Skeptic', role: 'Questioner', color: '#10b981', icon: '🤔' },
            { name: 'Target', role: 'Subject', color: '#6366f1', icon: '🎯' }
        ]
    },
    'trust-exploitation': {
        flow: `
            <div class="flow-box">🤝 Build Trust</div>
            <span class="flow-arrow">→</span>
            <div class="flow-box">💝 Deep Connection</div>
            <span class="flow-arrow">→</span>
            <d
[truncated — 33595 more characters]
```

### backend/app/main.py

```python
"""
Main entry point for the Social Experiment Simulation Platform
"""

import uvicorn
from .routes import app

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000, workers=4)
```

[25 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]