extropy-run 0.3.0

Predictive intelligence through agent-based population simulation

Predictive intelligence through agent-based population simulation.

Website · Announcement · CLI Reference · Architecture

---

Extropy creates synthetic populations grounded in real-world distributions, connects them in social networks, and simulates how they respond to events — each agent reasoning individually via LLM.

Simulate anything: Policy changes. Pricing decisions. Product launches. Crisis response. Any scenario where humans form opinions, make decisions, and influence each other.

Install

pip install extropy-run
export OPENAI_API_KEY=sk-...

Requires Python 3.11+. uv recommended.

Quick Start

STUDY=runs/congestion-tax && DB=$STUDY/study.db && mkdir -p $STUDY

# Build population + network
extropy spec "500 Austin TX commuters" -o $STUDY/base.yaml -y
extropy extend $STUDY/base.yaml -s "Response to $15/day congestion tax" -o $STUDY/population.yaml -y
extropy sample $STUDY/population.yaml --study-db $DB --seed 42
extropy network --study-db $DB -p $STUDY/population.yaml --seed 42

# Run simulation
extropy scenario -p $STUDY/population.yaml --study-db $DB -o $STUDY/scenario.yaml -y
extropy simulate $STUDY/scenario.yaml --study-db $DB -o $STUDY/results --seed 42

# Results
extropy results --study-db $DB
extropy results --study-db $DB --segment income

How It Works

1. Population — LLM discovers attributes, researches real-world distributions, samples agents
2. Network — Connects agents by similarity; edge types affect information flow
3. Two-pass reasoning — Agent role-plays reaction, then classifier extracts outcomes
4. Propagation — Opinions spread through network; agents update after hearing from peers

Features

Feature	Description
Population
Any geography	US, Japan, India, Brazil — define attributes with your distributions
Real grounding	LLM researches actual demographics, cites sources
Household mode	Correlated partners, NPC dependents, assortative mating
Agent focus	Primary adult, couples, or full families as reasoning agents
Network
Structural edges	Partner, household, coworker, neighbor, congregation, school parent
Similarity edges	Acquaintances and online contacts from attribute similarity
Small-world	Calibrated clustering coefficient and path lengths
Simulation
Two-pass reasoning	Role-play first, classify second — eliminates central tendency bias
Conversations	Agents talk to each other; both update state independently
Memory	Full reasoning history with emotional trajectory
Conviction	Affects sharing probability and flip resistance
THINK vs SAY	Internal monologue separate from public statement
Timeline events	New information injected at specified timesteps
Outcomes
Categorical	Known decision space (buy/wait/skip)
Boolean	Binary decisions (will share, will switch)
Float	Intensity measures (sentiment, likelihood)
Open-ended	Free text — discover categories post-hoc

Development

git clone https://github.com/exaforge/extropy.git && cd extropy
pip install -e ".[dev]"
pytest

License

MIT