🔮 Prophet

The wind tunnel for marketing campaigns

Test your campaign on 10,000 AI agents before you spend a dollar on the launch.

🚀 Quick Start · ✨ Features · 🎯 Use Cases · 📊 Comparison · 📖 Docs · 🤝 Contributing

git clone https://github.com/showjihyun/prophet.git
cd prophet && docker compose up -d
open http://localhost:5173

That's it. 5 minutes from clone to your first simulation. No API keys required to start — Prophet runs fully locally on a laptop.

---

💡 Why Prophet?

Focus groups lie — 10 humans in a room cannot tell you how a message spreads through a community. A/B tests are too late — by the time you have data, you're already paying for the launch. Brand-lift studies take 6 weeks, cost $50K, and tell you nothing about why a message failed.

Every discipline that ships things at scale — aerospace, civil engineering, software — gets to simulate before it builds. Marketing doesn't. Until now.

You take your campaign. You drop it into a virtual society of 10,000 AI agents organized into the communities you actually care about. You watch what happens.

---

✨ Features

🧠 6-Layer Agent Engine Each agent perceives, remembers, feels, cognizes, decides, and influences — powered by LLM cognition with persistent per-agent memory.	💰 Under $5 per run 3-tier inference (80% local SLM + 10% heuristic + 10% elite LLM) keeps 10K-agent simulations radically cheap. A naive GPT-4 run costs ~$15K.	🌐 Realistic networks Hybrid Watts-Strogatz + Barabási-Albert generator produces realistic clustering, power-law influencers, and cross-community bridges.
🎥 Watch it spread Real-time 3D WebGL graph (three.js) with orbit / zoom / pan controls, community-colored nodes, and cascade highlighting.	🔥 Auto-cascade detection Viral cascades, polarization, echo chambers, collapse, slow adoption — detected and timeline-marked as the simulation runs.	🔌 Multi-LLM ready Ollama, Claude, OpenAI, Gemini, + 2026 Chinese flagships (DeepSeek, Qwen, Moonshot Kimi, Zhipu GLM) out of the box.
🚨 Mid-run intervention Pause any time, Inject Event (controversy / endorsement / regulation), or Replay from step N to branch the timeline and try a different shock.	⚙️ Live engine control Dial the SLM / LLM ratio while the simulation is paused. Trade cost for reasoning depth without restarting from step 0.	🔀 Compare scenarios Run the same campaign with one variable changed. Compare view puts adoption / sentiment / cascades side by side. Clone any run in one click.

---

🚀 Quick Start

🐳 Docker (recommended)

GPU — NVIDIA (strongly recommended)

docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
docker compose exec ollama ollama pull llama3.1:8b

On an RTX 4070-class GPU, llama3.1:8b runs at ~75 tok/s — sub-second per agent tick.

CPU-only (no NVIDIA)

docker compose up -d
export OLLAMA_DEFAULT_MODEL=llama3.2:1b SLM_MODEL=llama3.2:1b
docker compose up -d --force-recreate backend
docker compose exec ollama ollama pull llama3.2:1b

Service endpoints

Service	URL
🖥️ Frontend	http://localhost:5173
⚙️ Backend API	http://localhost:8000
📘 API Docs (Swagger)	http://localhost:8000/docs

Open localhost:5173 → Projects → create a scenario with a campaign message → click Run All. Watch the 3D graph spread in real time.

💻 Local development

# Backend
cd backend && uv sync && uv run uvicorn app.main:app --reload

# Frontend
cd frontend && npm install && npm run dev

---

🎮 What you actually do in the UI

Prophet is not just an engine — it's a workspace. Here's the loop you actually click through:

1. Set up. Projects → New Scenario → Campaign Setup. You name the campaign, write the message, dial in novelty / controversy / utility, set the budget, pick which communities it lands on, and choose how many steps to run (default 50).
2. Run. Run All for the whole sweep, or Step to advance one tick at a time and watch the 3D graph spread. Pause any time.
3. Intervene mid-run. While paused you can:
   • Inject Event — drop a sudden shock (Controversy / Celebrity Endorsement / Regulatory Change / etc.) targeting all or specific communities. Takes effect on the next step.
   • Engine Control — change the SLM / LLM ratio live. Trade cost for reasoning depth without restarting.
   • Replay from step N — branch the simulation at any past step and try a different intervention from there.
4. Read the result. When it completes you get a Summary Report (adoption curve, sentiment, top community, scrollable Key Events timeline) and the dedicated Analytics page with deep deltas, cascade timeline, and shareable deep links.
5. Drill into why. Opinions lets you go scenario → community → individual conversation thread. Top Influencers ranks who actually moved the needle. Agent Interview asks any single agent why it decided what it did.
6. Compare. Run the same campaign with one variable changed (different message, different intervention, different population) and the Compare view shows them side by side. Clone any scenario in one click to start the next variant.

This is the loop. Most decisions get made between steps 3 and 6 — set it up once, run it many ways.

---

🎯 Use Cases

🧃 Pre-test a product launch

A beverage brand was about to spend $1.2M launching a sustainability product. Ran the message against 5,000 agents (15% skeptics, 60% mainstream, 20% early adopters, 5% influencers). Prophet showed the message polarized skeptics and adoption stalled at 13%. They reframed and hit 78% by the same step in the second simulation.

💉 Pre-screen public health messages

A health agency tested 3 vaccine messages against a 5K-agent virtual population. Strategy B caused near-zero adoption in skeptical communities (no viral cascade events in the first 4 steps). Strategy C triggered three positive cascades through influencer nodes by step 4. They picked C — adoption lift was 312× at the early-step horizon.

🏢 Stress-test internal communications

A Fortune 500 ran their RTO mandate through a synthetic employee population (4,500 engineering-heavy agents). Prophet predicted complete stall + slide into negative sentiment (mean_belief = -0.23, zero cascades). Restructured with carve-outs: same population hit 94% adoption with +0.68 sentiment — a +91-point swing from restructuring alone.

🚨 Stress-test crisis response (mid-run shock injection)

A consumer brand wanted to know how a sudden negative PR event would derail an ongoing campaign. Ran the campaign normally for 20 steps (adoption climbing toward 64%), then mid-run injected Controversy + "battery explosion in 47 units" + 0.9 via the Inject Event modal targeting only the skeptic community. The next 8 steps showed adoption stall at 41% and sentiment crash from +0.42 to -0.31, with two negative cascade events on the timeline. They tested two response messages on top: "transparent recall + free replacement" recovered to 58% by step 30; "deny and deflect" drove a third cascade and stalled at 19%. Crisis playbook went from gut-feel to rehearsed.

🔬 Computational social science research

Open-source. Reproducible. Runs on a laptop. Built-in cascade detection. If you've been wanting to do agent-based diffusion research without renting a GPU cluster, Prophet is for you.

Reproducible. Every claim above is verified end-to-end against the current engine in docs/USE_CASE_PILOTS.md, with raw per-step JSON in docs/pilot_results/. Re-run any pilot with uv run python backend/scripts/run_use_case_pilot.py --case <name>.

---

📊 How Prophet compares

	Prophet	OASIS (academic)	AnyLogic	Focus groups
💵 10K-agent simulation cost	under $5	free	$15K+ license	$30K+
⏱️ Time to first result	5 minutes	hours	days	6 weeks
🧠 LLM-driven agent cognition	✅	✅	❌	n/a
🎨 Real-time 3D visualization	✅	❌	✅	❌
🌊 Cascade / echo chamber detect	✅	❌	❌	❌
📈 Marketing-specific metrics	✅	❌	partial	✅
🆓 Open source	MIT	MIT	❌	n/a
💻 Runs on a laptop	✅	✅	✅	n/a

Numbers are rough order-of-magnitude based on public pricing and running comparable workloads. Your mileage will vary.

---

📸 Screenshots

3D Simulation Workspace — community-colored agents, real-time cascade glow, adopted-node tinting per community. Inject Event / Engine Control / Replay live in the sidebar.	Opinions Hierarchy — drill from scenario → community → individual conversation thread. See exactly which messages drove the consensus or the polarization.
Post-Run Analytics — adoption curve, sentiment trajectory, per-community breakdown, cascade timeline. Deep-link any metric for sharing.	Top Influencers — power-law influencers ranked by network reach + step-by-step propagation contribution. Find who actually moved the needle.

Screenshots not rendering? They live in docs/assets/screenshots/ — a fresh clone may be missing them while we record the next batch.

---

📐 The math & social science under the hood

Prophet isn't a "vibes" simulator. Every layer is a published, peer-reviewed model — wired together so you can change one knob and see the rest react. This section names the techniques and the academic lineage so reviewers, grad students, and skeptical CMOs can audit it.

Every claim below cites the source file. Search the repo for SPEC: docstrings to trace each technique back to its formal contract.

🌐 Network structure

Technique	What it does in Prophet	Source
Watts-Strogatz small-world	Per-community local clustering with rewiring p — captures the "friend of a friend" structure of real social ties	network/community_graph.py
Barabási-Albert preferential attachment	Generates the influencer/hub layer with a power-law degree distribution — a few accounts hold most of the reach	network/influencer_layer.py
Hybrid hub-merging + bridge edges	BA hubs are spliced into WS communities; cross-community bridges are degree-weighted (preferential) so brokers form realistically	network/generator.py
Personality homophily	Edge weights boosted by Manhattan-distance similarity across 5 traits — likes attract, but not exclusively	network/generator.py:390
Validation: clustering coefficient · modularity · degree assortativity	Generated networks are rejected unless 0.2 ≤ CC ≤ 0.6 and modularity is non-trivial — guarantees real-network character	network/generator.py:486

Why this matters: random graphs (Erdős-Rényi) systematically underestimate cascade behavior because they have no clustering and no hubs. Prophet's hybrid generator is calibrated to reproduce the structural signatures of empirical online communities (Watts 1998; Barabási-Albert 1999; Newman 2003).

🧠 Opinion & belief dynamics

Deffuant bounded-confidence model — agents only listen to neighbors whose belief is within an "open mind" radius

belief_i(t+1) = belief_i(t) + μ · (belief_j(t) − belief_i(t)) only if |belief_i − belief_j| < ε (default ε = 0.3, μ = 0.5). This is the canonical mechanism that allows polarization to emerge endogenously — without it, every model collapses to consensus. (Deffuant, Neau, Amblard, Weisbuch 2000.) → opinion_dynamics.py

Friedkin-style stubbornness — convergence rate is dampened by an agent's stubbornness trait

μ' = μ · (1 − stubbornness) so loyal-to-prior agents barely move even when exposed to contrary views. Generalizes Friedkin-Johnsen by tying anchor weight to a trait. → opinion_dynamics.py:36

Expert influence (sentiment shift) — credentialed agents nudge community sentiment with a configurable α

E_community(t+1) = clamp(E_community(t) + α · O_expert) with α = 0.3. Lets you study the asymmetry between official sources and grassroots voices. → sentiment_model.py:64

🌊 Diffusion & contagion

Technique	Implementation
SIR-inspired state machine	Agents transition SUSCEPTIBLE → EXPOSED → ADOPTED/REJECTED — the canonical epidemic model adapted for information goods
Calibrated propagation probability	P = max(0.1, I)·T·σ(−4·E)·MS where I=influence, T=trust, E=emotion, MS=message strength — a logistic-modulated multiplicative form
RecSys-inspired exposure	Two-phase candidate-gen + ranking: score = w₁·recency + w₂·social_affinity + w₃·interest_match + w₄·engagement + w₅·ad_boost − diversity_penalty (top-K feed). Mirrors industry recommender-system practice
Negative-cascade amplification	Negative events trigger asymmetric (≤ 0) sentiment deltas — operationalizes the "bad-news-travels-faster" finding (Vosoughi, Roy, Aral 2018)
Reddit-style hot score (optional)	`h = sign(net) · log₁₀(max(

🔥 Emergent-behavior detection

Five auto-detectors fire as the simulation runs and surface on the timeline:

Event	Trigger formula	File
Viral cascade	adoption_rate ≥ 0.15 in one step OR step-delta ≥ 0.15	cascade_detector.py:109
Slow adoption	adoption_rate < 0.02 for ≥ 5 consecutive steps (fires once, resets on recovery)	cascade_detector.py:155
Polarization	community sentiment_variance > 0.05 (sample variance, n−1 Bessel correction)	cascade_detector.py:210
Collapse	adoption drops ≥ 20% over 3 steps	cascade_detector.py:235
Echo chamber	internal_links / external_links > 10 (returns max ratio across communities)	cascade_detector.py:275

🎲 Monte Carlo & uncertainty

Aggregate	Formula	File
Viral probability	fraction of N runs that fire ≥ 1 viral cascade	simulation/monte_carlo.py:149
Expected reach	mean final adoption across runs	line 152
P5 / P50 / P95 reach	sorted-index percentile lookup (no interpolation — stable for small N)	line 154

Each MC run replays the same SimulationConfig with seed = base_seed + run_id × 1000 for full reproducibility.

🤖 Cognition cost-control (LLM tier routing)

Phase 1: experts ∪ {agents with influence > 0.7} ∪ critical-decision agents → Tier 3 (Elite LLM)
Phase 2: {influence > 0.5} ∪ {skeptic_skepticism > 0.7}                     → Tier 2 (heuristic + LLM blend)
Otherwise                                                                    → Tier 1 (local SLM)
Caps: max_tier3_ratio ≤ 10%, max_tier2_ratio ≤ 10%

This is what keeps a 10K-agent run under $5 while keeping the high-leverage decisions on a frontier model. → agent/tier_selector.py

---

🔬 What this means for social science

Prophet is, in academic terms, an agent-based model (ABM) of opinion dynamics on a generative social network with calibrated viral-diffusion mechanics. Three traditions converge:

1. Bounded-confidence opinion dynamics (Deffuant 2000, Hegselmann-Krause 2002) — the "open-minded radius" mechanism that produces clustering rather than consensus.
2. Generative network models (Watts-Strogatz 1998, Barabási-Albert 1999) — the structural backbone that lets micro-rules produce macro-patterns matching real platforms.
3. Computational diffusion (Kempe-Kleinberg-Tardos 2003 cascade models, plus modern RecSys-augmented exposure) — the pipeline a message follows from impression to adoption.

Why it's useful

🎓 For researchers A reproducible substrate for replicating ABM papers without writing your own simulator Built-in cascade / polarization / echo-chamber detectors mean you can study macro-patterns, not just micro-mechanics Per-step JSON export → drop straight into pandas / R / Jupyter LLM-driven cognition lets you study message content effects, not just topology — a frontier ABMs have struggled with

📣 For practitioners Pre-test message variants against synthetic populations whose composition you control Quantify uncertainty (P5 / P50 / P95 reach) before you spend Identify which communities will polarize before the campaign hits them Study counterfactuals — "what if we removed this influencer?" / "what if the message was 0.2 less controversial?" — at zero risk

🏛️ For policy & public health Pre-screen public-health messaging for asymmetric uptake across communities Test crisis-comms variants under simulated information shocks Forecast the polarization risk of contested policy announcements Compare informational interventions (transparency, framing) against structural ones (network seeding)

🧪 For social-science pedagogy A live ABM students can run and break — the textbook diagrams come alive The 6-step UI maps cleanly to a research workflow (Generate → Inject → Simulate → Detect → Visualize → Decide) Open source means students can read the equations in the same place the simulator runs them

Honest limitations

Prophet is a model — and all models are wrong, some are useful. Things to be honest about:

• Calibration is structural, not empirical. Network statistics (clustering, modularity) are validated against ranges from the literature — not against your specific platform's logs.
• LLM agents inherit LLM biases. Tier 3 cognition uses general-purpose LLMs; their persona play is consistent but is not a substitute for actual human focus-group data.
• Bounded-confidence dynamics are a theory, not a measurement. Different opinion-dynamics models (DeGroot, voter, Hegselmann-Krause) produce different predictions; we picked Deffuant for its empirical track record on polarization, but reasonable researchers disagree.
• Five emergent-behavior detectors do not exhaust the space. We picked the five most common in the diffusion literature; novel patterns will need custom detectors (PRs welcome).

In other words: use Prophet to generate hypotheses, narrow your search space, and rule out obvious failure modes — not to replace empirical validation on real audiences.

---

🏗️ Architecture

1. Generate     → 10K agents in 5 communities (early adopters, mainstream,
                  skeptics, experts, influencers) with realistic clustering,
                  scale-free degree, and bridge nodes

2. Inject       → Your campaign / message / policy

3. Simulate     → Each agent runs the 6-layer loop
                  (perception → memory → emotion → cognition → decision → influence)

4. Detect       → Viral cascades, polarization, echo chambers, collapse,
                  slow adoption — auto-marked on the timeline

5. Visualize    → 3D WebGL graph with orbit / zoom / pan,
                  community-colored nodes and edges, WebSocket live updates

6. Decide       → Compare scenarios, export JSON / CSV, share links

---

🧰 Tech Stack

Layer	Stack
🖼️ Frontend	React 18 · TypeScript · Vite · Tailwind · react-force-graph-3d (three.js) · Cytoscape.js
🧵 State	Zustand · TanStack Query · native WebSocket
⚙️ Backend	Python 3.12 · FastAPI (async) · SQLAlchemy 2.0 · Pydantic v2
🤖 LLM	Ollama (local SLM) · Claude · OpenAI · Gemini · DeepSeek · Qwen · Moonshot Kimi · Zhipu GLM
🗄️ Database	PostgreSQL 16 + pgvector
⚡ Cache	Valkey
🧪 Testing	pytest (1,031) · Vitest (736) · Playwright (E2E)
📦 Package	uv (Python) · npm (Node)

---

🧪 What's working today

• ✅ 6-layer agent engine with LLM-driven cognition
• ✅ 3-tier inference keeping 10K-agent simulations under $5
• ✅ Real-time 3D WebGL graph that scales to 5K+ nodes
• ✅ Cascade, echo chamber, polarization auto-detection from real network topology
• ✅ WebSocket live streaming with pause / resume / step / run-all
• ✅ 8 LLM providers first-class — Ollama, Claude, OpenAI, Gemini + 4 Chinese flagships (2026)
• ✅ 1,767+ automated tests with Playwright E2E coverage

🟡 In progress: hosted Cloud Starter tier, scenario template library, validation studies 🔮 Planned: plugin SDK, Segment / mParticle / HubSpot integrations, multi-language agents

Full history → CHANGELOG.md · Roadmap discussion → ROADMAP.md

---

📖 Documentation

• 📘 API Docs → http://localhost:8000/docs (Swagger UI when running)
• 🛠️ Contributing Guide — setup under 10 minutes
• 🤝 Code of Conduct
• 🔒 Security Policy
• 📜 Changelog
• 🗺️ Roadmap
• 🌿 Git Branch Strategy

---

⭐ Star History

If Prophet is useful to you, a star is the fastest way to help others find it.

---

🤝 Contributing

We need help. Specifically:

• 🐛 Bug reports with reproduction steps
• 📝 Documentation improvements (typos, clarity, examples)
• 🧪 Test cases for edge cases you find
• 🌱 good first issue picks — small, clearly-scoped tasks for newcomers
• 💡 Use cases — tell us what you're trying to simulate; we may already support it

Start here:

1. Read CONTRIBUTING.md
2. Browse good first issue
3. Open a Discussion before any large change
4. Open a PR — we aim to respond within 48 hours

Maintainers are active. First-time contributors get a thank-you and a fast review. We label every issue, keep the roadmap public, and publish what we ship.

👥 Contributors

---

🗣️ Community

• 💬 GitHub Discussions — questions, ideas, show-and-tell
• 🐞 GitHub Issues — bugs and feature requests

If you build something cool with Prophet, we want to see it. Open a Discussion and post a screenshot.

---

🙏 Inspiration & Acknowledgments

Prophet stands on the shoulders of many other projects.

MiroFish — biggest architectural influence

MiroFish combined OASIS (academic agent simulator) with GraphRAG and Zep Cloud for long-term memory. It proved LLM-driven agents with persistent memory could be assembled into a coherent pipeline. Prophet takes that idea, opens it up, makes it cheaper through tiered inference, and adds the marketing-specific layer (cascade detection, viral metrics, real-time viz) that MiroFish doesn't focus on.

Other prior art we learned from

• OASIS — academic foundation for large-scale agent-based social simulation
• GraphRAG (Microsoft Research) — hybrid vector + graph retrieval pattern
• NetworkX — hybrid WS+BA generator would have taken months instead of days without it
• three.js / react-force-graph-3d — 3D rendering; instanced sphere rendering scales to thousands of nodes
• Cytoscape.js — EgoGraph 2D force-directed layout
• Ollama — local SLM inference makes the 3-tier cost model possible
• Hugging Face / open-weight LLM community — proved small models are good enough for agent reasoning
• NetLogo and MASON — showed decades ago that simulating a society is a tractable engineering problem

If you contributed to any of these and feel we should credit you more specifically, open a PR — we'll fix it.

---

📜 License

MIT — see LICENSE.

Use it commercially. Fork it. Modify it. Embed it. We just ask you to keep the license file and not pretend you wrote it from scratch.

---

📚 Citation

If Prophet helps your research, please cite:

@software{prophet_2026,
  title  = {Prophet: A simulation engine for marketing campaign diffusion},
  author = {Prophet Contributors},
  year   = {2026},
  url    = {https://github.com/showjihyun/prophet}
}

---

Built because marketing deserves a wind tunnel. Open-sourced because everyone deserves one.

_{Made with ⚡ and way too much coffee · ⬆ back to top}