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)")]

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 → environment → population → run → report → iterate. Each stage writes one schema-validated artifact you can inspect and edit.
Versioned iteration

Changing a study that already ran goes through a version gate: snapshot, iterate, branch from any earlier version — nothing is silently overwritten.
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.
Bring your own simulator

Wrap an existing legacy simulator behind the core interfaces with zero edits to its source — or build a study from scratch on the core kernel.
Typed contracts everywhere

Pydantic schemas define every hand-off (Persona → Observation → Action → metrics); strict validation guards each stage boundary.

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¶

git clone https://github.com/REPLACE-ME/socioverse   # TODO(launch): final repo URL
cd socioverse
pip install -e .
pytest tests -q          # data-dependent tests auto-skip

Then either drive it agentically — open the repo in Claude Code 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 reference studies ship with the repository, each forkable as a starting point for your own variant:

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
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