Metadata-Version: 2.4
Name: silisocs
Version: 0.1.0
Summary: A native social simulation framework for configurable social-media experiments
Author-email: Austin Welch <austinmw89@gmail.com>
License-Expression: MIT
Project-URL: Documentation, https://sandbox-social.github.io/silisocs
Project-URL: Repository, https://github.com/sandbox-social/silisocs
Keywords: agent-based simulation,social simulation,llm,social media
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: coloredlogs>=15.0.1
Requires-Dist: openai<2.0.0,>=1.35.9
Requires-Dist: tqdm<5.0.0,>=4.66.4
Requires-Dist: termcolor<3.0.0,>=2.4.0
Requires-Dist: docstring-parser<0.17,>=0.16
Requires-Dist: networkx<4.0.0,>=3.3
Requires-Dist: requests<3.0.0,>=2.32.3
Requires-Dist: psutil<8.0.0,>=7.0
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: omegaconf<3.0.0,>=2.3.0
Requires-Dist: pyyaml<7.0.0,>=6.0.2
Requires-Dist: hydra-core<2.0.0,>=1.3.2
Requires-Dist: python-dotenv<2.0.0,>=1.0.1
Requires-Dist: typer>=0.12.0
Provides-Extra: concordia
Requires-Dist: gdm-concordia<2.2.0,>=2.1.0; extra == "concordia"
Provides-Extra: analysis
Requires-Dist: dash<3.0.0,>=2.18.2; extra == "analysis"
Requires-Dist: dash-cytoscape<2.0.0,>=1.0.2; extra == "analysis"
Requires-Dist: ipympl<0.10.0,>=0.9.4; extra == "analysis"
Requires-Dist: matplotlib<4.0.0,>=3.9.1; extra == "analysis"
Requires-Dist: nbformat<6.0.0,>=5.10.4; extra == "analysis"
Requires-Dist: plotly<6.0.0,>=5.22.0; extra == "analysis"
Requires-Dist: powerlaw<2.0.0,>=1.5; extra == "analysis"
Requires-Dist: python-louvain<0.17,>=0.16; extra == "analysis"
Requires-Dist: scipy<2.0.0,>=1.14.1; extra == "analysis"
Requires-Dist: seaborn<0.14.0,>=0.13.2; extra == "analysis"
Requires-Dist: tiktoken<0.8.0,>=0.7.0; extra == "analysis"
Provides-Extra: dashboard
Requires-Dist: streamlit<2.0.0,>=1.45.1; extra == "dashboard"
Provides-Extra: docs
Requires-Dist: properdocs>=1.6.7; extra == "docs"
Requires-Dist: mkdocs-autorefs>=1.4.4; extra == "docs"
Requires-Dist: mkdocs-gen-files>=0.6.1; extra == "docs"
Requires-Dist: mkdocs-literate-nav>=0.6.3; extra == "docs"
Requires-Dist: mkdocs-material>=9.7.6; extra == "docs"
Requires-Dist: mkdocstrings-python>=2.0.3; extra == "docs"
Requires-Dist: pymdown-extensions>=10.21.2; extra == "docs"
Provides-Extra: hf
Requires-Dist: datasets<5.0.0,>=4.5.0; extra == "hf"
Provides-Extra: mastodon
Requires-Dist: loguru<0.8.0,>=0.7.2; extra == "mastodon"
Requires-Dist: mastodon-py<2.0.0,>=1.8.1; extra == "mastodon"
Requires-Dist: pyvis==0.3.1; extra == "mastodon"
Provides-Extra: hpc
Requires-Dist: submitit<2.0.0,>=1.5.1; extra == "hpc"
Requires-Dist: hydra-submitit-launcher<2.0.0,>=1.2.0; extra == "hpc"
Provides-Extra: recsys
Requires-Dist: scikit-learn<2.0.0,>=1.5.0; extra == "recsys"
Requires-Dist: scipy<2.0.0,>=1.14.1; extra == "recsys"
Requires-Dist: sentence-transformers<4.0.0,>=3.0.1; extra == "recsys"
Provides-Extra: viz
Requires-Dist: fastapi[all]>=0.110.1; extra == "viz"
Requires-Dist: gunicorn>=21.2.0; extra == "viz"
Requires-Dist: jinja2<4.0.0,>=3.1.4; extra == "viz"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "viz"
Provides-Extra: aws
Requires-Dist: boto3<2.0.0,>=1.34.139; extra == "aws"
Provides-Extra: all
Requires-Dist: silisocs[analysis,concordia,dashboard,docs,hf,hpc,mastodon,recsys,viz]; extra == "all"
Dynamic: license-file

[![CI](https://github.com/sandbox-social/silisocs/actions/workflows/test.yml/badge.svg)](https://github.com/sandbox-social/silisocs/actions/workflows/test.yml)
[![Docs](https://github.com/sandbox-social/silisocs/actions/workflows/docs.yml/badge.svg)](https://sandbox-social.github.io/silisocs/)

**NOTE: This repository is currently in alpha development, and we expect to ship further stability updates over the coming weeks**

# SiliSocS

SiliSocS (Silicon Society Sandbox) is an easy-to-use, configurable, and extensible framework for multi-agent
social simulation and experimentation. It is structured around the EASE decomposition —
Environment, Agents, Simulation engine, and Evaluation — taking inspiration from the Concordia framework, and providing a principled,
reproducible configuration layer for simulated societies. It offers scenario-driven 
social grounding, Concordia-like game master-mediated environments, local and served 
backends, evaluation probes, runtime telemetry, and experimental study tooling. Interoperability for Concordia designed agents is available through an optional bridge extra.

- 2026 ICML Position Paper [ICML 2026](https://www.complexdatalab.com/stamina/papers/puelmatouzel_CloseEvalGap.pdf)
- 2026 EASE Configuration: [arXiv:2605.30258](https://arxiv.org/abs/2605.30258)
- Documentation: [sandbox-social.github.io/silisocs](https://sandbox-social.github.io/silisocs)

Papers on a previous version centered on a served Mastodon social media network:
- 2024 NeurIPS Workshop Paper: [arXiv:2410.13915](http://arxiv.org/abs/2410.13915)
- 2025 IJCAI Demo Paper: [IJCAI 2025](https://www.ijcai.org/proceedings/2025/1271)

## Install

The default package is intentionally lean and supports local simulations without
dashboard, Mastodon, HuggingFace, or analysis dependencies:

```sh
pip install silisocs
```

Optional integrations are exposed as extras:

```sh
pip install "silisocs[hf]"        # Hugging Face persona sources
pip install "silisocs[mastodon]"  # real Mastodon backend
pip install "silisocs[dashboard]" # Streamlit launcher
pip install "silisocs[analysis]"  # plotting and analysis dashboards
pip install "silisocs[viz]"       # local backend web visualizers
pip install "silisocs[concordia]" # optional Concordia bridge
pip install "silisocs[hpc]"       # optional Submitit/Slurm study helpers
```

For contributor work from a checkout:

```sh
git clone https://github.com/sandbox-social/silisocs.git
cd silisocs
uv sync --all-extras --group dev --group docs
```

## Quick Start

Run the built-in package default scenario:

```sh
uv run silisocs
```

For a local smoke test without model API calls:

```sh
uv run silisocs sim.llm.provider=scripted
```

Override scale or model settings with Hydra dot notation:

```sh
uv run silisocs num_agents=10 num_steps=5 sim.llm.name=gpt-4o
```

Run a bundled external scenario:

```sh
uv run silisocs --config-path scenarios/election/conf
```

Run the packaged resource-market preset:

```sh
uv run silisocs scenario=resource_market agents=resource_market env=resource_market
```

Run the packaged virtual-space preset:

```sh
uv run silisocs scenario=virtual_space agents=virtual_space env=virtual_space
```

The same backends also have curated external examples under `scenarios/`:

```sh
uv run silisocs --config-path scenarios/resource_market/conf scenario=resource_market agents=resource_market env=resource_market
uv run silisocs --config-path scenarios/virtual_space/conf scenario=virtual_space agents=virtual_space env=virtual_space
```

Outputs are written under `outputs/<scenario_name>/<jobname>/` and include
`action_events.jsonl`, `probe_events.jsonl`, `prompts_and_responses.jsonl`,
`sim_metrics.json`, a resolved Hydra config snapshot, and a local
SQLite backend database for local platforms.

## Studies and Experiments

Study orchestration lives in `experiments/run_study.py`. It expands hypotheses,
conditions, scenarios, and seeds into reproducible simulation runs, then executes
the configured evaluators and writes organized artifacts under the study's
`generated/` directory.

```sh
uv run python -m experiments.run_study --study experiments/studies/study_template_v1 plan
uv run python -m experiments.run_study --study experiments/studies/study_template_v1 run --only-hypothesis h1_timeline_mechanism
uv run python -m experiments.run_study --study experiments/studies/study_template_v1 summary-append --author analyst --hypothesis h1_timeline_mechanism --note "Initial finding"
```

Custom commands plug in through `conditions.<id>.execution.command`, evaluator
commands through the `evaluations` list, and optional HPC setup through the
study runner's `submitit` or `slurm-array` commands. See
[docs/experiments.md](docs/experiments.md) and
[docs/study_schema.md](docs/study_schema.md).

## Architecture

The canonical runtime entry point is `src/silisocs/runtime/runner.py`. It
composes Hydra configuration, builds agents, initializes memory, constructs the
environment backend and game master, runs the simulation engine, and writes
artifacts.

```text
silisocs/
├── src/silisocs/
│   ├── agents/              # Native and bridge-compatible runtime agents
│   ├── conf/                # Packaged Hydra defaults
│   ├── dashboard/           # Optional Streamlit scenario launcher
│   ├── environments/        # Game masters and environment backends
│   ├── evaluations/         # Probes, telemetry, and optional analysis tools
│   ├── runtime/             # Runner, config projection, and orchestration
│   └── simulation_engines/  # Engine loop, step, and turn policies
├── scenarios/               # Scenario configs and curated inputs
├── experiments/             # Study orchestration and generated study outputs
├── docs/                    # ProperDocs documentation
└── tests/                   # Unit and integration tests
```

## Optional Concordia Bridge

SiliSocS runs on native runtime contracts by default. The optional Concordia
bridge is for porting Concordia-designed agents or components without
making Concordia part of the default install:

- All runtime agents satisfy `silisocs.agents.base_agent.Agent`.
- Native runtime classes and GM components are the primary extension API.
- Legacy Concordia-shaped components are isolated behind
  `silisocs.adapters.concordia`.
- Scenario YAML selects builders, backends, policies, probes, and prompts so
  most experiment designs do not require Python edits.

See [docs/concordia_bridge.md](docs/concordia_bridge.md) and
[docs/building_agents.md](docs/building_agents.md) for the extension contracts.

## Development

Common commands:

```sh
uv run pytest
uv run silisocs-config-dry-run --project-root .
uv run poe lint
uv build --sdist --wheel
uv run --group docs properdocs build --strict
```

- `uv run pytest` runs the test suite in the current environment.
- `uv run silisocs-config-dry-run --project-root .` composes shipped scenario
  and replication configs without running LLM calls.
- `uv run poe lint` runs the configured formatting, static checks, and type
  checks.
- `uv build --sdist --wheel` builds release artifacts in `dist/`.
- `uv run --group docs properdocs build --strict` builds the documentation site
  and fails on broken links or stale navigation.
