Society0 is a general social simulation engine for agent-assisted research. Actors share one environment; plugins implement its internal mechanisms. Rule and LLM drivers use the same information and action interfaces, while code schedules define the study's timing and ordering.
The package version is defined in pyproject.toml. This branch contains the redesigned Core; release readiness and outstanding validation are tracked in the implementation checklist. Existing artifacts must be read using their producing version.
Follow the first run and recovery tutorial to install from a chosen source revision, run two rule actors, read actual results and continue the remaining time in a new directory. It uses the base package and needs no model account. Python 3.12 or later and macOS or Linux are supported by the storage implementation.
For assistant-guided research, install the complete Society0 skill folder in your coding assistant's skill directory, preserving its references and assets. The skill guides research design; the Python package executes experiments. A two-round LLM study is minimal_experiment.py. It includes persistent identity, perception, a domain action, explicit experience extraction and structured measurement. Its quickstart explains provider setup.
Use the functional dependency groups required by your study: llm, memory, social, shell and observe. Base rule runs need no model endpoints or Rust build. The LLM file tools use the native filesystem package, with its own wheel and source build requirements; see installation.
Codex subscription access is configured through the subscription guide. The llm extra provides the Pydantic AI integration; simulation actions and complete Thread history remain owned by Society0. The model and driver contracts describe the integration boundary.
Plugin declares services, explicit dependencies, schema and initialization. compose establishes the shared state before installing services. ActorRecord describes persistent identity and subjective state; actor_plugin builds drivers only when needed. rule_driver_plugin and llm_driver_plugin expose factories through ordinary plugin services. Activation extensions share cognition and memory between drivers; restored actor records resolve their stored driver names against those services.
Information provides discoverable documents and datasets with authorized totals, continuation cursors and complete original-content reads. Actions exposes templates against resource references and rechecks eligibility when invoked. LLMDriver offers these through meta tools and an optional Bashkit shell, preserving the full Thread. RuleDriver accesses the same structured interfaces.
Schedule supplies the next simulation time and ordered Phase sequence; Runtime executes and publishes that complete step. Serial execution is the default; explicitly independent phases can run concurrent actors. Endpoint and shared request limits separately bound external calls. Completion, waiting and incomplete outcomes remain distinct.
The two-mechanism conversation plan, external graph initialization, typed records and immutable catalog demonstrate reusable mechanisms. Detailed contracts are in docs/core-next.
RunPlan and run_plan freeze the public run contract and execute complete steps. Preserve code, dependency and configuration identities, and supply credentials through the runtime environment. Every attempt uses its own run directory.
python -m society0.kernel.observation /path/to/run
python -m society0.kernel.observation /path/to/run --serve 8711Install the observe extra to start the HTTP server. Observation reads live diagnostics, Thread tails, resource usage, action outcomes and results. Fixed complete views support historical analysis. Large records retain original-content references and byte-range continuation. The observation contract explains version boundaries, API examples and costs; the workbench renders recorded experiment outputs.
Keep observed simulation outcomes separate from empirical claims. Preserve all information needed for decisions, actionable domain operations, original messages and fact ordering. Memory writing, recall and active tools are independently configured. Provider failures and budget truncation remain visible; a successfully readable checkpoint alone does not establish scientific validity.
Run the deterministic suite with the development dependencies. Real endpoint tests use an explicit environment profile and separate output directory.
uv sync --all-extras
uv run pytest -m 'not real_e2e'The implementation overview links the current contracts and measured limits. Architecture boundaries are in PROJECT.md, semantic parity in the capability map, and historical investigations retain their original source versions under research/.