Murmur

Multi-agent social media simulation engine

Upload any document. Generate a knowledge graph. Simulate how hundreds of AI agents react on social media — in real time.

Quick Start · Architecture · Setup Guide · API Reference · Contributing

---

What is Murmur?

Murmur turns any text document into a living social media simulation. Give it a news article, a policy memo, or a product announcement — it extracts every person, company, and organization, builds a knowledge graph of their relationships, generates unique AI personas for each entity, and then simulates how they'd react on Twitter and Reddit.

Every agent has its own personality, opinions, communication style, and social network. They post, reply, argue, like, and repost — all streamed to your browser in real time.

Features

Knowledge Graph Engine

• Automatic ontology generation from any text document (entity types + relationship types)
• Named Entity Recognition extracts every person, company, and organization
• Relationship extraction maps connections between entities
• Interactive D3.js force-directed graph visualization with edge labels

Simulation Engine

• 100-200+ AI agent personas generated per simulation, each with unique personality, MBTI type, communication style, stance, and opinions
• Three-tier agent system: Key Opinion Leaders (tier 1), Active Participants (tier 2), Crowd (tier 3)
• Dual-platform simulation: Twitter (short, punchy posts with hashtags) and Reddit (long-form analysis and debate)
• Opinion dynamics with SIR contagion model — ideas spread through the social network
• PageRank-based influence weighting and community detection
• Feed ranking algorithm (recency, relevance, popularity, viral threshold)

Real-Time Streaming

• Server-Sent Events (SSE) stream every agent action to the browser as it happens
• Live typing indicators show which agents are currently composing
• Graph nodes pulse and highlight as agents become active
• Round-by-round progress tracking in the status bar

Analysis & Reporting

• Built-in report agent with tool-calling capabilities
• Post-simulation agent interviews — chat directly with any persona
• Surveillance monitoring: opinion shifts, community dynamics, engagement patterns
• Interaction statistics and network evolution tracking

Developer Experience

• Single SQLite database — no external database dependencies
• Any OpenAI-compatible LLM provider (OpenAI, Anthropic, MiniMax, Ollama, Groq, etc.)
• Clean Vue 3 + Pinia frontend with composable architecture
• FastAPI backend with hot reload

Quick Start

Prerequisites

• Node.js 18+ (npm or bun)
• Python 3.11+ (pip or uv)
• An OpenAI-compatible API key (OpenAI, MiniMax, Groq, Together, or any compatible provider)

1. Clone

git clone https://github.com/codejunkie99/murmur.git
cd murmur

2. Backend

cd backend-v2
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Create a .env file:

LLM_API_KEY=your-api-key-here
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini

Start the server:

uvicorn main:app --port 5001

3. Frontend

cd frontend
npm install
npm run dev

4. Open

Navigate to http://localhost:3000. Upload a document, type a simulation prompt, and click Run simulation.

How It Works

Murmur runs a 7-stage pipeline — fully automated after you click Run:

Document Upload
      |
      v
[1] Ontology Generation -----> LLM designs entity types + relationship types
      |
      v
[2] NER Extraction ----------> LLM extracts all entities + relationships from text
      |
      v
[3] Knowledge Graph ----------> Nodes + edges stored in SQLite, rendered with D3.js
      |
      v
[4] Persona Generation ------> LLM creates unique persona for each entity
      |                         (personality, MBTI, style, stance, opinions)
      v
[5] Simulation Config --------> LLM generates seed posts, platform assignments,
      |                         timing, narrative direction
      v
[6] Simulation Execution -----> Agents post/reply/like/repost in rounds
      |                         SSE streams each action to the browser live
      v
[7] Report Generation --------> Tool-calling agent analyzes the simulation results

Each simulation round:

1. Feed ranking selects relevant posts for each agent
2. LLM generates agent actions (post, reply, like, repost, or skip)
3. Opinion shifts are applied based on agent interactions
4. Crowd dynamics generate reactions from tier-3 agents
5. Network evolution updates social connections
6. All actions are persisted and streamed via SSE

Configuration

Environment Variables

Create backend-v2/.env with:

Variable	Required	Default	Description
LLM_API_KEY	Yes	—	API key for your LLM provider
LLM_BASE_URL	No	https://api.minimax.io/v1	OpenAI-compatible API endpoint
LLM_MODEL	No	MiniMax-M2.7-highspeed	Model name for structured generation
EXA_API_KEY	No	—	Exa API key for URL research feature

LLM Provider Examples

OpenAI:

LLM_API_KEY=sk-...
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini

Groq:

LLM_API_KEY=gsk_...
LLM_BASE_URL=https://api.groq.com/openai/v1
LLM_MODEL=llama-3.1-70b-versatile

Together AI:

LLM_API_KEY=...
LLM_BASE_URL=https://api.together.xyz/v1
LLM_MODEL=meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo

Ollama (local, free):

LLM_API_KEY=ollama
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL=llama3.1

MiniMax:

LLM_API_KEY=your-minimax-key
LLM_BASE_URL=https://api.minimax.io/v1
LLM_MODEL=MiniMax-M2.7-highspeed

Architecture

murmur/
├── backend-v2/              # FastAPI Python backend
│   ├── main.py              # App entry point, router registration
│   ├── engine.py            # Simulation engine (round execution)
│   ├── engine_agent.py      # Agent LLM interaction (prompts + parsing)
│   ├── agent_prompts.py     # System/feed prompt builders
│   ├── agents.py            # Agent class definition
│   ├── graph.py             # Ontology generation + NER extraction
│   ├── personas.py          # Persona generation from graph entities
│   ├── sim_prepare.py       # Full prepare pipeline orchestration
│   ├── config_gen.py        # LLM-generated simulation config
│   ├── llm.py               # OpenAI-compatible LLM client
│   ├── db.py                # SQLite schema + query helpers
│   ├── feed.py              # Feed ranking algorithm
│   ├── network.py           # Social network (igraph)
│   ├── analytics.py         # PageRank, community detection, SIR model
│   ├── dynamics.py          # Crowd behavior simulation
│   ├── posts.py             # Post store (in-memory + SQLite)
│   ├── routes_*.py          # API route handlers (13 routers)
│   ├── report_agent.py      # Tool-calling report generation agent
│   └── surveillance/        # Real-time monitoring system
├── frontend/                # Vue 3 SPA
│   ├── src/
│   │   ├── views/           # Page-level components (Workspace, Launchpad)
│   │   ├── components/      # UI components (graph, feed, agents, report)
│   │   ├── composables/     # Reactive logic (useWorkspace, useForceGraph)
│   │   ├── stores/          # Pinia state (simulation, project, ui, report)
│   │   └── api/             # HTTP client (graph, simulation, report)
│   ├── index.html
│   └── vite.config.js
└── backend/                 # Legacy v1 backend (reference only)

See ARCHITECTURE.md for the full technical deep-dive.

API Reference

All endpoints are prefixed with /api.

Graph

Method	Endpoint	Description
POST	/api/graph/ontology/generate	Upload document + generate ontology
POST	/api/graph/build	Build knowledge graph from ontology
GET	/api/graph/data/{project_id}	Get graph nodes + edges
GET	/api/graph/task/{task_id}	Check build task status

Simulation

Method	Endpoint	Description
POST	/api/simulation/create	Create simulation from project
POST	/api/simulation/prepare	Generate agent personas + config
POST	/api/simulation/start	Start simulation execution
POST	/api/simulation/stop	Stop running simulation
GET	/api/simulation/{id}	Get simulation details
GET	/api/simulation/{id}/profiles	Get agent profiles
GET	/api/simulation/{id}/stream	SSE stream of live actions
GET	/api/simulation/{id}/prepare-stream	SSE stream of persona generation

Feed & Actions

Method	Endpoint	Description
GET	/api/simulation/{id}/actions	Get all simulation actions
GET	/api/simulation/{id}/feed	Get formatted feed
GET	/api/simulation/{id}/run-status	Get round/action counts

Report

Method	Endpoint	Description
POST	/api/report/generate	Start report generation
GET	/api/report/{id}	Get generated report
GET	/api/report/{id}/status	Check report status

Interview

Method	Endpoint	Description
POST	/api/simulation/interview/batch	Batch interview agent personas
GET	/api/simulation/{id}/interview/history	Get interview history

Example Simulation Prompts

• "Simulate how Wall Street banks, retail investors, and SEC regulators react on Twitter over 48 hours to SpaceX allocating 30% of its IPO to retail investors"
• "Simulate the social media fallout when a major AI lab announces it will open-source its frontier model"
• "Predict how gaming communities, developers, and investors respond to a surprise acquisition of a beloved indie studio by a major publisher"
• "Model the public discourse around a new FDA decision to approve a controversial gene therapy"

Contributing

Contributions are welcome. Here's how to get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Make your changes
4. Test locally (both frontend and backend)
5. Submit a pull request

Development Setup

# Backend with auto-reload
cd backend-v2
source .venv/bin/activate
uvicorn main:app --port 5001 --reload

# Frontend with HMR
cd frontend
npm run dev

Areas for Contribution

• New LLM providers — add provider-specific optimizations
• Agent behavior — improve prompt engineering in engine_agent.py
• Visualization — enhance the D3 graph or feed components
• Analysis — add new surveillance monitors or report tools
• Performance — optimize LLM call batching and concurrency

License

MIT License. See LICENSE for details.

---

Built by @Av1dlive