SocioVerse

A longitudinal, LLM-native social-simulation runtime.

Most LLM social-simulation frameworks run cross-sectional studies: many single-round experiments over changing crowds. SocioVerse tracks the same population over time — panel data — by fixing the population and making the environment dynamic.

The unifying abstraction is Lewin's field theory — B = f(P, E) (behaviour is a function of person and environment):

• P — population: a fixed pool of personas with persistent ids (the longitudinal key).
• E — environment: dynamic, on two axes: physical / information × macro / local.
• B — behaviour: computed each step. The loop closes E_t → B_t → E_{t+1}, recording one panel row per agent per step.

flowchart LR
    E0["E<sub>t</sub><br/>environment"] -->|observe| P["P<br/>fixed population"]
    P -->|"decide · B = f(P, E)"| B["B<sub>t</sub><br/>behaviour"]
    B -->|apply| E1["E<sub>t+1</sub>"]
    E1 -.->|next step| E0
    B -->|record| D[("panel store<br/>(DuckDB)")]

Two loops run on that abstraction. The longitudinal simulation loop advances one run, step by step: E_{t+1} = g(E_t, B_t). The controllable research loop advances the study — one edit at a time over the study state σ = (P, E_{0:T}, f, Θ), so σ_{k+1} = h(a_k, σ_k). Both run on one agentic infrastructure: the workflow skills, the data services that resolve P and E from real data, and the records that make a finished study auditable.

What you get

• Panel data, not snapshots

  ---

  The same agents, step after step. Query any individual's trajectory, or the aggregate metrics, straight from a durable DuckDB store.

• An agentic workflow, end to end

  ---

  Seven sv-* workflow skills take you from a research question to a report: route → model → environment → population → run → report → iterate. Each stage writes one schema-validated artifact you can inspect and edit, then stops at a checkpoint. The reporting stage covers analysis, literature and the manuscript draft.

• Intervene and branch

  ---

  An intervention is one declaration in the environment bundle — a ScheduledEvent on a physical layer or a Broadcast to an audience, fired at a step. A branch replays its parent's history exactly and pays only for the steps from its fork step on, so control and treatment stay comparable agent by agent. How branching works

• Versions you control

  ---

  A version snapshots the whole workspace. Any artifact may change — population, behaviour function, environment, run settings — and a new version can start from any earlier one. Nothing is silently overwritten, and every run is reproducible from its snapshot. The research loop

• Grounded, not invented

  ---

  Every study carries a grounding sidecar: facts with sources, modeling references, and declared assumptions. Load-bearing values cite where they came from.

• Typed contracts, any simulator

  ---

  Pydantic schemas define every hand-off (Persona → Observation → Action → metrics) and strict validation guards each stage boundary. Implement the four interfaces on the core kernel, or wrap an existing legacy simulator behind them with zero edits to its source.

Try it without installing anything

A hosted instance runs at socioverse.fudan-disc.com. Describe a research question in ordinary language and a research assistant builds the study with you — grounding it, running it, and writing the report — while every artifact appears in an observation pane beside the conversation. Same runtime, same workflow, same study directory; nothing to set up.

Start at SocioVerse Online.

A 60-second tour

SocioVerse2 is open source (Apache-2.0): GitHub · Releases (v0.2.0, see Releases) · PyPI.

git clone https://github.com/sii-research/SocioVerse2.git
cd SocioVerse2
pip install -e ".[dev,viz]"      # Python 3.11+
pytest -q                        # no key needed; tests that need a companion repo or a live LLM skip
python scripts/demo_offline.py   # a full study end to end, offline, no API key

pip install socioverse2 installs the core library alone (import name socioverse); the workflow skills, the dashboard and the reference studies come with the clone.

Then either drive it agentically — open the repo in Claude Code (which runs on its own Claude login, not on the simulation's LLM key) and start from your research question:

/sv-init "How does a rumor spread through a mid-sized online community
          when an official correction is broadcast on day 3?"

…or programmatically — load a study's validated artifacts, assemble them with socioverse.engine.build_simulator, run, and query the results with SQL:

SELECT step, state FROM panel WHERE agent_id = '…' ORDER BY step;  -- one agent over time
SELECT * FROM metrics ORDER BY step;                               -- the trajectory
SELECT step, note FROM events ORDER BY step;                       -- interventions fired

Continue with Installation → Quickstart, or read the Concepts first.

Worked cases

Five worked cases, each a starting point for your own variant. Four ship with the repository (Chicago and Sugarscape run on the companion SocioVerse-ABM checkout, consumer confidence on ConsumerSim); drug procurement is documented as a pattern and is not part of the open-source release:

case	what it demonstrates
Chicago segregation	wrapping a legacy simulator; real census data; a policy intervention that falsified its own hypothesis
Consumer confidence	a longitudinal axis made of information accrual rather than calendar time
Hybrid opinion dynamics	a hybrid population — LLM-driven core users alongside rule-driven ordinary ones
Drug procurement	a study whose run lives in an external training pipeline
Sugarscape	LLM f versus rule f, checked for parity against the original model