Skip to content

Quickstart

There are two ways to drive SocioVerse. They produce the same artifacts and the same queryable outputs.

  • Agentic (recommended) — open the repo in Claude Code and let the bundled sv-* workflow skills take you from a research question to a report, pausing at every stage for your review.
  • Programmatic — assemble a study directory with the Python API and run it yourself.

Path 1 — the agentic workflow

Open socioverse/ as the project in Claude Code and start a fresh session (skills are discovered at session start). Then start from your question:

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

sv-init first routes your query against the catalog of already-built studies, then scaffolds a new study under studies/<id>/. From there each skill writes one schema-validated artifact and pauses for you to inspect or edit it before the next stage:

stage skill writes
route & scope /sv-init study.yaml + grounding/grounding.json
model (from-scratch path only) /sv-build-model model.py
environment E /sv-build-environment environment/environment.json
population P /sv-build-population population/population.json + population/roster.jsonl
run /sv-run trajectory/study.duckdb + metrics_history.json
report /sv-report reports/report.md + figures
change it later /sv-iterate versions.json + versions/vN/ snapshots

You control the cadence: "build everything, prompt me before /sv-run" or "do the whole pipeline" both work — each artifact still surfaces as it passes.

The agentic pipeline: one validated artifact per stage, checkpoints between stages, a spend gate before the run

Routing: reuse, build, or wrap

sv-init decides among three paths before any code is written:

  • Path A — reuse/adjust: an existing study already covers your question → it is forked to a new study_id and only the fork's artifacts are edited. No new code.
  • Path B — build from scratch: nothing matches → /sv-build-model implements the four core interfaces natively. The default for a new question.
  • Path C — wrap your own simulator: you bring an existing legacy simulator → see Wrap a Legacy Simulator.

Inspect what got produced

Every stage output is a plain file under studies/<id>/:

S=studies/<your-study-id>
cat $S/study.yaml                    # the StudySpec: question, n_steps, metrics
cat $S/environment/environment.json  # E: layers + scheduled events + broadcasts
cat $S/population/population.json    # P: personas, count, interaction structure
cat $S/population/roster.jsonl       # the instantiated agents' t=0 state
cat $S/reports/report.md             # the rendered trajectory + intervention notes

Path 2 — programmatic

A study directory is data (validated JSON artifacts) plus — for from-scratch studies — a model.py whose classes self-register on import. Assembling a run is four validated loads and one call:

import studies.your_study  # noqa: F401 — side effect: @register() runs
                           # (the shipped template is studies/opinion_diffusion)

from socioverse.engine import build_simulator
from socioverse.validation import validate_handoff
from socioverse.schemas import EnvironmentBundle, PopulationBundle, SimulationConfig

S = "studies/your_study"
env_b   = validate_handoff(f"{S}/environment/environment.json", EnvironmentBundle)
pop_b   = validate_handoff(f"{S}/population/population.json",  PopulationBundle)
sim_cfg = validate_handoff(f"{S}/simulation/simulation.json",  SimulationConfig)

sim = build_simulator(
    env_bundle=env_b, pop_bundle=pop_b, sim_config=sim_cfg,
    store_path=f"{S}/trajectory/study.duckdb",
)
history = sim.run()   # E_t → B_t → E_{t+1}; panel + metrics land in DuckDB

build_simulator resolves the *_ref strings in the artifacts against the registry and returns a ready LongitudinalSimulator; run() returns the MetricsHistory.

For a no-token dry run (no LLM spend, deterministic), see LLM Clients & Dry Runs.

Read the results

The run lands in a durable DuckDB store you can query directly:

-- one agent over time (the longitudinal view)
SELECT step, state FROM panel WHERE agent_id = '…' ORDER BY step;

-- the aggregate trajectory
SELECT * FROM metrics ORDER BY step;

-- which interventions fired, and when
SELECT step, note FROM events ORDER BY step;

duckdb studies/<your-study-id>/trajectory/study.duckdb

Where to go next