The Belief Engine

A terminal-based cognitive dissonance society simulator grounded in Festinger's social psychology research. Watch 40 agents with competing philosophical beliefs encounter each other, argue, and resolve psychological tension — live, in your terminal.

  ●  ●            ●
     #   !    ●      ○  ○
  ●     ●   ●   #      ●
     ○   ●         ●     #
  !     ●   ○   ●    ○
     ●     ●   !      ●

What It Does

Each agent holds a weighted belief vector across 10 philosophical dimensions:

Dimension	Low ↔ High
authority	Flat structures ↔ Hierarchy
tradition	Innovation ↔ Preservation
fairness	Equality of opportunity ↔ Equality of outcome
harm_aversion	Liberty/risk ↔ Safety/protection
purity	Pragmatic ethics ↔ Sacred/profane distinctions
loyalty	Universalism ↔ In-group solidarity
progress	Precautionary principle ↔ Techno-optimism
autonomy	Collective coordination ↔ Individual agency
scarcity	Positive-sum worldview ↔ Zero-sum worldview
truth	Perspectival truth ↔ Objective reality

Agents encounter each other each tick. When beliefs clash beyond a threshold, cognitive dissonance triggers one of four resolution strategies:

Strategy	Who Uses It	What Happens
Assimilation	Open-minded	Updates toward the other's position
Entrenchment	Dogmatic	Digs in; rationalizes peripheral beliefs
Rejection	All	Increases confidence in current view
Inversion	Contrarians	Pressure causes the opposite of intended effect

The live visualization maps all agents into 2D belief-space (individualism vs. traditionalism), color-coded by personality, updating in real time.

Installation

No dependencies beyond Python 3.7+. Just clone and run.

git clone https://github.com/Gabangxa/belief-engine.git
cd belief-engine
python3 main.py

Needs a terminal at least 110 columns × 40 rows for the live visualization. Use --no-viz on smaller screens.

Usage

# Live visualization (default)
python3 main.py

# Watch echo chambers crystallize from a polarized start
python3 main.py --preset polarized --seed 42

# Watch consensus slowly emerge
python3 main.py --preset consensus --steps 500 --no-viz --report

# Headless run with full statistical analysis
python3 main.py --no-viz --report

# Tune population and speed
python3 main.py --agents 80 --steps 400 --speed fast

# Reproducible run (same seed = same story every time)
python3 main.py --seed 1337

All Flags

Flag	Default	Description
--agents N	40	Population size
--steps N	300	Simulation steps
--seed N	random	Random seed for reproducibility
--preset	random	Starting conditions: random, polarized, consensus
--speed	normal	Render speed: slow, normal, fast
--no-viz	off	Headless mode (no live display)
--report	off	Print statistical analysis after run

Agent Personalities

Symbol	Color	Type	Behavior
●	Green	Open-minded (25%)	Readily updates beliefs toward others
#	Red	Dogmatic (25%)	Resists updating; entrenches under pressure
!	Magenta	Contrarian (10%)	Pressure causes inversion or deep entrenchment
+	Blue	Pragmatist (20%)	Updates proportional to confidence gap
○	Yellow	Social mirror (20%)	Strongly mimics high-confidence agents

What to Observe

• --preset polarized: Two echo chambers crystallize within ~10 steps and lock permanently — dogmatic agents cluster, contrarians become permanent outliers.
• --preset consensus: Open-minded and social mirror agents drag the society toward moderate ground over hundreds of steps.
• --preset random: Emergent chaos — sometimes consensus, sometimes fragmentation, always surprising.

Tuning

Edit config.py to reshape the society:

# More dogmatic society → more polarization
PERSONALITY_WEIGHTS = { "dogmatic": 0.5, "open_minded": 0.1, ... }

# Faster belief change
BASE_UPDATE_RATE = 0.25

# Tighter echo chamber detection
ECHO_CHAMBER_SIMILARITY_THRESHOLD = 0.85

Project Structure

belief_engine/
  main.py       — CLI entry point and simulation loop
  agent.py      — Agent class with personality + dissonance resolution
  beliefs.py    — BeliefGraph data structure
  dynamics.py   — Encounter scheduling, topic selection, cascade detection
  society.py    — Simulation container and metrics
  renderer.py   — Live ANSI terminal visualization
  analytics.py  — End-of-run statistical report
  config.py     — All tunable parameters
  tests.py      — Test suite (85 tests)

Tests

python3 tests.py

The Science Behind It

The simulation is grounded in Leon Festinger's cognitive dissonance theory (1957): when a person holds two conflicting beliefs simultaneously, they experience psychological discomfort and are motivated to reduce it — either by changing a belief, acquiring new information, or reducing the importance of the conflicting cognition.

The personality types map loosely to empirical findings in social psychology:

• Dogmatism correlates with belief perseverance under counter-evidence (Lord et al., 1979)
• Social mirroring reflects conformity effects (Asch, 1951)
• Contrarian inversion reflects psychological reactance (Brehm, 1966)

---

Built with Claude Code. Zero external dependencies.