Installation¶

SocioVerse2 is open source under Apache-2.0: github.com/sii-research/SocioVerse2 (releases, current v0.2.0, see Releases). The core library is also on PyPI as socioverse2.

Requirements¶

Python 3.11+
A POSIX-ish shell (macOS / Linux; Windows via WSL works too)
Optionally, an LLM API key. It is not required to install, run the tests, or run a full study offline (see no-token mode).
For the /sv-* workflow skills, a coding agent with its own login. The simulation's LLM key does not power it; see what powers the workflow skills.

Install from source (recommended)¶

Clone the repository: it carries the runtime and the workflow skills, the local research dashboard and the reference studies. We recommend a dedicated environment (conda or venv):

condavenv

git clone https://github.com/sii-research/SocioVerse2.git
cd SocioVerse2

conda create -n socioverse python=3.11 -y
conda activate socioverse
pip install -e ".[dev,viz]"

git clone https://github.com/sii-research/SocioVerse2.git
cd SocioVerse2

python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,viz]"

Verify the install (no key needed):

pytest -q

Some tests skip — that's expected

Tests that need a companion repository, an optional extra (chicago, workbench) or a live LLM detect what is missing and auto-skip. A run with skips and zero failures is a healthy install.

Or: the core library from PyPI¶

pip install socioverse2      # import name: socioverse

This installs the core library only (socioverse: schemas, interfaces, engine, DuckDB store, validation). The /sv-* workflow skills, the dashboard, the reference studies and the demo script are not part of the package; they come with the clone above. Use the PyPI package when you drive studies from your own Python code (Quickstart, path 2).

Run a study without an API key¶

python scripts/demo_offline.py

Running opinion_diffusion_demo (a local copy of opinion_diffusion): 12 agents, 4 steps, llm_kind=scripted

step  mean_opinion  opinion_std  frac_above_0_5
   0         0.500        0.288            0.50
   1         0.500        0.282            0.50
   2         0.618        0.212            0.67
   3         0.707        0.160            0.83
   4         0.737        0.142            1.00

The script forks the shipped reference study studies/opinion_diffusion into a local study, studies/opinion_diffusion_demo/ (gitignored, like every study you create), validates the copied artifacts and runs it there. The decision model runs with llm_kind: "scripted", a deterministic rule, so the run is free and reproducible. The run lands in the demo study's trajectory/ and the rendered report in its reports/ (English by default; --report-lang zh for Chinese). The reference study is never written to, and each run starts the demo afresh.

Every run is a DuckDB store you can query with SQL:

import duckdb
con = duckdb.connect("studies/opinion_diffusion_demo/trajectory/study.duckdb", read_only=True)
con.sql("SELECT step, state->>'opinion' AS opinion FROM panel WHERE agent_id = 'od-000' ORDER BY step").show()
con.sql("SELECT * FROM metrics ORDER BY step").show()
con.sql("SELECT step, note FROM events ORDER BY step").show()

Run stores are not committed

trajectory/ folders and *.duckdb files are gitignored, so the shipped reference studies carry their artifacts and rendered reports but no run store. To query a study with SQL, run it first (the demo above does this for opinion_diffusion).

Open the research dashboard¶

python dashboard/server/app.py --open     # http://127.0.0.1:8787 (use --port to change it)

The demo shows up as its own study next to the reference opinion_diffusion. The dashboard is a local, read-only view over studies/; the /sv-* skills start it automatically when a study begins. See The Run Dashboard.

Configure the LLM (optional)¶

To run the same study with a real LLM:

pip install -e ".[llm]"
cp .env.example .env      # set SV_LLM_API_KEY; .env is gitignored, never commit keys
python scripts/demo_offline.py --llm openai

The script probes the endpoint once, then makes 48 short calls (12 agents × 4 steps) and replaces the demo study's run. Replies that do not parse fall back to the rule and are counted in the output. The shipped run prompted the model in Chinese; add --prompt-lang en for the English prompt.

SocioVerse reads LLM settings from the environment or from .env (looked up at $SV_HOME/.env, then ./.env, then the repository root; the process environment wins):

variable	meaning
`SV_LLM_API_KEY`	the key for the simulated agents' LLM calls
`SV_LLM_BASE_URL`	optional; any OpenAI-compatible endpoint (unset: the official OpenAI API)
`SV_LLM_MODEL`	optional; read by `scripts/demo_offline.py`, the Chicago adapter and studies whose `simulation.json` names no model
`OPENAI_API_KEY`	fallback when `SV_LLM_API_KEY` is empty. The `abm_*` studies' LLM mode reads `OPENAI_API_KEY` and `OPENAI_BASE_URL` directly

Where a study's model is pinned

The shipped from-scratch studies pin their model in simulation.json (decision_args.model), consumer_confidence in environment.json (prediction.model), and the ABM studies in the task's config.yaml in SocioVerse-ABM. On an endpoint that does not serve that model, change it there, or through /sv-iterate for a study that has already run.

Never hard-code secrets

Keys belong in the gitignored .env (or your shell environment), never in code or study artifacts.

What powers the workflow skills¶

A /sv-* study uses two separate LLM connections, set up separately:

The coding agent that runs the skills. Claude Code needs its own Claude login (a Claude subscription) or an ANTHROPIC_API_KEY. The SV_LLM_* key in .env does not power Claude Code; it only reaches the simulated agents. Codex CLI is an experimental alternative: it reads AGENTS.md and the skills in .codex/skills/, both shipped in the repository and generated from the Claude Code side, but the Codex path has not yet had a full end-to-end test. In Codex, name the stage in your prompt (for example Run sv-init: "How does a rumor spread ...").
The simulation's own LLM, which makes the simulated agents' decisions: any OpenAI-compatible provider, through the SV_LLM_* variables above. Without it a from-scratch study still runs end to end in the scripted mode, and /sv-run asks before it spends on real LLM calls.

/sv-lit (literature survey) needs one more extra: pip install -e ".[lit]".

Session hooks

.claude/settings.json and .codex/hooks.json register session hooks that run python3 dashboard/hooks/sv_emit.py. They only toggle the dashboard's "waiting for you" banner; the skills start the dashboard itself. Set SV_DASH_DISABLE=1 in the environment you launch the agent from to turn both off.

Extras¶

extra	adds
`llm`	the OpenAI-compatible client for real-LLM runs, with SOCKS proxy support
`viz`	matplotlib for report figures
`workbench`	`llm` + `viz`, plus textblob (the `hisim_roe` sentiment scorer) and openpyxl (the `germany_auto_market` workbook)
`lit`	the retrieval engine behind `/sv-lit`
`abm`	numpy and networkx for the 11 `abm_*` studies
`chicago`	the geo and Mesa stack of `chicago_schelling`, plus everything in `abm`
`dev`	pytest, build, twine
`all`	all of the above

Companion repositories¶

Some reference studies wrap a project that lives in its own repository. Clone it next to SocioVerse2 and it is found automatically; the matching tests stop skipping.

workspace/
├── SocioVerse2/
├── SocioVerse-ABM/                               # the 11 abm_* studies and chicago_schelling
└── ConsumerSim-Consumer-Confidence-Forecast/     # consumer_confidence

SocioVerse-ABM holds 11 classic agent-based models, each with a rule and an LLM behaviour function, and the Chicago segregation model with its census data:

cd ..                                              # the folder that contains SocioVerse2
git clone https://github.com/Lishi905/SocioVerse-ABM.git
cd SocioVerse2
pip install -e ".[dev,chicago,workbench]"
pytest -q                                          # the ABM and Chicago tests now run

The companion folder must be named exactly SocioVerse-ABM. ConsumerSim is the forecasting pipeline consumer_confidence wraps, and HiSim is optional (hisim_roe runs without it). For other layouts, set SV_ABM_ROOT, SV_CHICAGO_LEGACY, SV_CONSUMERSIM_ROOT or SV_HISIM_ROOT in your shell or in .env.

Configure external services (optional)¶

.env is the single source of service endpoints and keys. The Python clients read it directly, and the in-session MCP registration is generated from it — never hand-written:

python scripts/gen_mcp_json.py     # renders the gitignored .mcp.json from .env

Re-run that after every edit to .env. Two optional capabilities are wired this way; an entry is emitted only when its *_URL variable is set:

capability	variables	notes
Event service — real-world macro/news context for E	`SV_EVENT_API_URL`, `SV_EVENT_API_KEY`, optional `SV_EVENT_LOCAL_CACHE`	the URL is the full MCP endpoint including its path (e.g. `http://host:9997/event_mcp`), not a bare host; the key is sent as `Authorization: Bearer`
User-pool survey MCP — real X / 小红书 personas for P	`SV_USER_POOL_MCP_URL`, `SV_USER_POOL_MCP_KEY`	the service requires bearer auth, so the key is not optional here

Both services are hosted by the SocioVerse team and are not part of the repository; to request access, email contact@socioverse.fudan-disc.com. The hosted workbench has both configured.

Everything degrades gracefully without them: the events client falls back to a local cache and then to plain web search, and populations fall back to grounded synthesis or your own persona file. Details, health probes, cost and fallback rules: External Capabilities.

No-token mode¶

Everything in the pipeline except the actual LLM decision call runs without a key: install, tests, environment/population building, and any study whose decision model is rule-based. The from-scratch studies switch their LLM off with llm_kind: "scripted" in simulation.json (decision_args), which is how scripts/demo_offline.py runs; chicago_schelling dry-runs with its own DeterministicLLMClient. See LLM Clients & Dry Runs.

Next step¶

Head to the Quickstart and run your first study.