Skip to content

Releases

Every release is tagged on GitHub, and the core library is published to PyPI:

The API reference on this site is generated from the main branch of the public repository.

v0.2.0 — 2026-09-25

The first public release of SocioVerse2. Release notes · PyPI 0.2.0 · SocioVerse-ABM v0.2.0 · technical report

What is included

  • Runtime (socioverse): a fixed population with persistent agent ids acts step by step in an environment that keeps changing, and every step records one panel row per agent in DuckDB. Interventions (scheduled events and audience-scoped broadcasts) fire at chosen steps; a counterfactual branch replays its parent's earlier steps exactly and pays only for the steps after the fork.
  • Workflow skills for Claude Code: /sv-init, /sv-build-model, /sv-build-environment, /sv-build-population, /sv-run, /sv-report, /sv-iterate, plus /sv-lit and /sv-paper. A Codex CLI mirror (AGENTS.md, .codex/skills/) ships as experimental.
  • Local research dashboard (dashboard/): overview, environment, population, dataset, experiments, literature and paper tabs, with version and branch history.
  • Reference studies: from-scratch templates (opinion_diffusion, campus_dining_choice), real-data cases (germany_auto_market, consumer_confidence_us_backtest, hisim_roe), a wrapper for the external ConsumerSim pipeline (consumer_confidence), and wrappers for the 11 classic ABMs and the Chicago segregation model in SocioVerse-ABM.
  • An offline demo (scripts/demo_offline.py): a full study end to end with no API key, and the same study on any OpenAI-compatible endpoint with --llm openai.

Get started

git clone https://github.com/sii-research/SocioVerse2.git
cd SocioVerse2
pip install -e ".[dev,viz]"
pytest -q
python scripts/demo_offline.py

Details in Installation.

Worth knowing

  • pip install socioverse2 installs the core library only. The workflow skills, the dashboard and the reference studies come with git clone.
  • The workflow skills need a coding agent with its own login (Claude Code, or the experimental Codex CLI path). The SV_LLM_* key only powers the simulated agents; see what powers the workflow skills.
  • Run stores (trajectory/, *.duckdb) are not committed. The reference studies ship their artifacts and rendered reports; run a study to query it.
  • hisim_roe and consumer_confidence_us_backtest are imported references (marked not re-runnable): their series come from the technical report and from the pinned ConsumerSim release data respectively.
  • The drug procurement case documented in this manual is not part of the open-source repository.

Since v0.2.0, on main

  • The DecisionModel documentation now states the call pattern plainly: decide_batch receives the whole step; from-scratch studies call the LLM once per agent, concurrently; legacy adapters keep the wrapped engine's own pattern.
  • /sv-init rewrites a forked study's title, question, hypothesis and metric descriptions in the language of your query, and /sv-report writes in that language.
  • /sv-run reports LLM fallbacks only from what a run actually recorded.
  • The PyPI badge and install line were added to the README.