Installation¶

Requirements¶

Python 3.11+
A POSIX-ish shell (macOS / Linux; Windows via WSL works too)
Optionally, an LLM API key — not required to install, run the tests, or dry-run a study (see no-token mode).

Install¶

We recommend a dedicated environment (conda or venv):

condavenv

conda create -n socioverse python=3.11 -y
conda activate socioverse

git clone https://github.com/REPLACE-ME/socioverse   # TODO(launch): final repo URL
cd socioverse
pip install -e .

git clone https://github.com/REPLACE-ME/socioverse   # TODO(launch): final repo URL
cd socioverse
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e .

Verify the install:

pytest tests -q

Some tests skip — that's expected

Tests that depend on large external datasets detect missing data and auto-skip. A run with skips and zero failures is a healthy install.

Extras are available for optional features:

pip install -e ".[dev]"    # + pytest
pip install -e ".[viz]"    # + matplotlib for report figures
# individual bundled studies may declare their own extras — see their READMEs

Configure the LLM (optional)¶

SocioVerse reads LLM settings from the environment:

variable	meaning
`SV_LLM_API_KEY`	the primary API key the runtime looks for
`OPENAI_API_KEY`	honored as a fallback key
`SV_LLM_BASE_URL`	optional endpoint override (any OpenAI-compatible gateway)
`SV_LLM_MODEL`	optional model selection

The repository ships a template — copy it and fill in your key:

cp .env.example .env      # .env is gitignored; never commit keys

Never hard-code secrets

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

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

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. For LLM-driven studies, a deterministic client stands in for the real one during plumbing checks, parity tests, and CI — see LLM Clients & Dry Runs.

Next step¶

Head to the Quickstart and run your first study.