Metadata-Version: 2.5
Name: agorasim
Version: 0.0.1
Summary: Multi-model LLM-agent opinion dynamics on social networks
Author: Theo Radicella
License: MIT
Requires-Python: >=3.11
Requires-Dist: diskcache>=5.6
Requires-Dist: litellm>=1.40
Requires-Dist: networkx>=3.2
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: pyarrow>=15
Requires-Dist: pydantic>=2.7
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tenacity>=8.2
Requires-Dist: typer>=0.12
Provides-Extra: analysis
Requires-Dist: duckdb>=1.0; extra == 'analysis'
Requires-Dist: matplotlib>=3.8; extra == 'analysis'
Requires-Dist: ruptures>=1.1; extra == 'analysis'
Requires-Dist: scikit-learn>=1.4; extra == 'analysis'
Requires-Dist: scipy>=1.12; extra == 'analysis'
Requires-Dist: seaborn>=0.13; extra == 'analysis'
Requires-Dist: statsmodels>=0.14; extra == 'analysis'
Description-Content-Type: text/markdown

# agorasim

Opinion dynamics with LLM agents on social networks, where different agents run on
**different language models**. Extends Wang et al. (COLING 2025) with a multi-model
ensemble and individual-level trajectory inspection.

## Setup

```bash
uv sync                      # core + dev tools
uv sync --extra analysis     # + DuckDB, statsmodels, ruptures, plotting
cp .env.example .env         # add API keys you need
```

## Usage

```bash
uv run agorasim baseline configs/bc_small_world.yaml   # numeric baseline + metrics
uv run agorasim ping ollama/llama3.1                   # check a model is reachable
uv run pytest
```

Runs are written to `runs/<timestamp>_<name>_s<seed>/`:
`meta.json` (config + git commit), `trajectory.parquet` (step, agent, opinion),
`metrics.parquet`.

## Layout

```
src/agorasim/
  config.py     typed YAML experiment configs (Pydantic)
  networks.py   Erdős–Rényi / Watts–Strogatz / Barabási–Albert, initial opinions
  baselines.py  DeGroot, bounded confidence, Deffuant, Friedkin–Johnsen
  metrics.py    polarization, global disagreement, neighbour correlation (Wang et al. §4.2)
  llm.py        one async client for every provider (LiteLLM) + disk cache + fake backend
  runs.py       run directories and Parquet output
  cli.py        `agorasim` command
```

## Models

Any LiteLLM model string works: `anthropic/…`, `openai/…`, `xai/…`, `deepseek/…`,
`ollama/…` (local), or `openai/<model>` with `api_base` pointing at a vLLM server (INDACO).
`fake/<anything>` is a deterministic offline backend for tests.

## Roadmap

- [x] M0 — skeleton, configs, LLM client, caching
- [x] M1 — networks, numeric baselines, metrics
- [ ] M2 — single-model LLM replication of Wang et al. (personas, memory, classifier scoring)
- [ ] M3 — multi-model ensemble
- [ ] M4 — rewiring + recommender
- [ ] M5 — individual trajectory tooling
- [ ] M6 — INDACO: vLLM + SLURM sweeps
- [ ] M7 — d3 visualization
