disensa 0.1.0__tar.gz

disensa-0.1.0/.env.example

@@ -0,0 +1,6 @@
+# Only fill in the providers you use. Never commit .env.
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+XAI_API_KEY=
+DEEPSEEK_API_KEY=
+OPENROUTER_API_KEY=

disensa-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+.cache/
+runs/
+dist/
+.pytest_cache/
+.ruff_cache/
+.DS_Store

disensa-0.1.0/CLAUDE.md

@@ -0,0 +1,71 @@
+# disensa — context for coding agents
+
+Bachelor's thesis project (BAI, University of Milan; supervisors Flaminio Squazzoni, Stefano Zapperi).
+LLM-agent opinion dynamics on social networks. It extends Wang et al. (COLING 2025,
+arXiv:2409.19338), who used a single LLM for every agent, in two directions:
+
+1. **Model heterogeneity**: different agents run on different LLMs (`ensemble.py`).
+2. **Individual-level inspection**: every agent's reading, reasoning and posts are logged, so
+   single trajectories can be traced and explained (`analysis.py`).
+
+Research questions are deliberately not fixed yet — do not invent or add them.
+
+## Conventions
+
+- **Git: never add `Co-Authored-By: Claude`, `Claude-Session:` or any other Claude attribution to
+  commit messages or PR descriptions, unless Theo explicitly asks.** Commits are authored by Theo only.
+- Opinions live on **[-2, 2]** everywhere (−2 strongly oppose, +2 strongly support the topic statement).
+- Everything is seeded. Personas depend only on `seed` (never on models), so the same
+  population can be replayed under different model mixes. Separate RNG streams:
+  feeds `seed`, personas `seed+1000`, model assignment `seed+2000`, rewiring `seed+3000`.
+- Days are synchronous: agents read day t−1 and all updates apply together.
+- The model is an agent attribute, separate from the persona.
+- One fixed scorer model rates every post (never the agent's own model) — Chuang et al.
+- LLM calls go through `LLMClient` only (LiteLLM + disk cache). `fake/<behaviour>` models run
+  offline and deterministically; use them in tests. Never call real APIs in tests.
+- Model output is untrusted: parse with `parse_json`, and a malformed reply must never crash a
+  run — log it in `error` and keep the previous state.
+- Run outputs: see the docstring in `runs.py`. Parquet for tables, JSONL for text.
+- Metrics follow Wang et al. §4.2 (`metrics.py`); cite the source in docstrings when adding more.
+
+## Layout
+
+```
+src/disensa/
+  config.py     Pydantic schemas for YAML experiment configs
+  networks.py   ER / WS / BA graphs, initial opinions
+  baselines.py  DeGroot, bounded confidence, Deffuant, Friedkin–Johnsen
+  metrics.py    polarization, global disagreement, neighbour correlation
+  personas.py   Wang-style personas (gender, age, education, Big Five)
+  prompts.py    every prompt template (quoted verbatim in the thesis)
+  llm.py        LiteLLM client, cache, JSON parsing/repair
+  fake_llm.py   offline deterministic backend
+  engine.py     the simulation loop
+  ensemble.py   model assignment strategies
+  rewiring.py   unfollow/follow network dynamics
+  analysis.py   loading runs, trajectories, shift detection and attribution
+  numeric.py    numeric baselines written in the run format (so they open in the app)
+  export.py     run → JSON for the page; `viz` embeds it (and d3) into one offline file
+  app.py        `disensa app`: local stdlib HTTP server + JSON API, runs in threads
+  static/       landing.html (start page at /), docs.html (/docs), app.html (the lab at /lab: header that expands into
+                the new-run form and runs list, plus the viewer), vendored d3.min.js. The project name is not shown in the UI for now;
+                model text is untrusted: insert with textContent only
+  cli.py        `disensa` command
+```
+
+## Commands
+
+```bash
+uv sync --extra analysis
+uv run pytest && uv run ruff check . && uv run ruff format --check .
+uv run disensa run configs/demo_fake.yaml     # offline, seconds
+uv run disensa run configs/quick.yaml         # Ollama, minutes
+uv run disensa inspect runs/<run_dir>         # per-model table + largest opinion shifts
+uv run disensa inspect runs/<run_dir> --agent 7
+uv run disensa app                            # web app: configure, run, watch live
+uv run disensa viz runs/<run_dir>             # single offline viewer file for one run
+```
+
+## Not done yet
+
+- M6: running on INDACO (vLLM + SLURM). The code only needs `api_base` pointed at a vLLM server.

disensa-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: disensa
+Version: 0.1.0
+Summary: Multi-model LLM-agent opinion dynamics on social networks
+Project-URL: Repository, https://github.com/theoradicella/disensa
+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
+
+# disensa
+
+Opinion dynamics with LLM agents on social networks, where different agents can run on
+**different language models**. It extends the Social Simulation Framework of Wang et al.
+(COLING 2025, arXiv:2409.19338), which used one LLM for every agent, with:
+
+- a **multi-model ensemble**: each agent's reasoning comes from a model you choose
+  (Claude, GPT, Grok, DeepSeek, Llama, Gemma, Mistral, Qwen, …);
+- **individual-level inspection**: every agent's reading, reasoning and posts are logged, so
+  you can trace how and why a single agent moved;
+- **network rewiring** (optional): agents unfollow people they disagree with;
+- an **interactive d3 viewer** for every run.
+
+## Setup
+
+```bash
+uv sync --extra analysis     # dependencies incl. analysis tools
+cp .env.example .env         # only if you use paid APIs
+```
+
+For free local models, install [Ollama](https://ollama.com) and pull a few:
+
+```bash
+ollama pull llama3.2:3b && ollama pull llama3.1:8b && ollama pull qwen2.5:7b
+OLLAMA_NUM_PARALLEL=4 OLLAMA_MAX_LOADED_MODELS=3 ollama serve
+uv run disensa ping ollama_chat/llama3.2:3b      # check it answers
+```
+
+## The app
+
+```bash
+uv run disensa app          # opens http://127.0.0.1:8765
+```
+
+The start page (a swarm of agents that scatters from your cursor) leads to the lab at `/lab`.
+
+Pick a preset or set everything by hand (engine, topology, initial opinions, models,
+recommender, rewiring, numeric algorithm), press **Run simulation**, and watch it live.
+Nodes are shaded from pale blue (oppose) to deep blue (support) and drift left to right with
+their opinion, so camps separate on screen. The **Runs** tab lists past runs to replay.
+Start with the `demo_camps` preset: offline, a few seconds.
+
+## Command line
+
+```bash
+uv run disensa run configs/demo_fake.yaml        # offline fake models, a few seconds
+uv run disensa run configs/quick.yaml            # 10 agents, 5 days, Ollama, a few minutes
+uv run disensa inspect runs/<run_dir>            # per-model behaviour + largest opinion shifts
+uv run disensa inspect runs/<run_dir> --agent 3  # one agent's day-by-day story
+uv run disensa viz runs/<run_dir>                # open the interactive viewer
+```
+
+| Config | What it is |
+|---|---|
+| `demo_camps.yaml` | Offline demo where the population splits into camps |
+| `demo_fake.yaml`, `demo_fake_rewiring.yaml` | Offline demos (fake models); try the whole pipeline for free |
+| `numeric_bc.yaml` | Classic bounded confidence, opens in the app like any run |
+| `quick.yaml` | Smallest real run on Ollama, for checking prompts |
+| `wang/{small_world,scale_free,random}.yaml` | Wang et al. replication, one model, 50 agents × 30 days |
+| `mixed_local.yaml` | Three open-weight models from three labs, on Ollama |
+| `mixed_api.yaml` | Claude, GPT, Grok, DeepSeek through their APIs (paid) |
+| `bc_small_world.yaml`, `fj_scale_free.yaml` | Numeric baselines (`disensa baseline`) |
+
+`--days N` overrides the number of days for a quick try.
+
+## How a run works
+
+1. **Network**: Erdős–Rényi, Watts–Strogatz or Barabási–Albert, seeded.
+2. **Agents**: each gets a persona (gender, age, education, Big Five poles, initial
+   opinion on [-2, 2]) and a model (`assignment`: balanced, random, or clustered by community).
+3. **Day 0**: every agent writes a first post about the topic.
+4. **Each day**: an agent reads a few posts from its neighbours (optionally only those
+   within the recommender threshold), then returns its reasoning, new belief, new post and an
+   updated memory in one call. A fixed scorer model rates every post on [-2, 2].
+5. **End of day**: optional rewiring; metrics are recorded.
+
+Everything is cached on disk, so re-running the same config costs nothing.
+
+## Run outputs
+
+`runs/<timestamp>_<name>_s<seed>/`
+
+| File | Contents |
+|---|---|
+| `meta.json` | config, git commit, timing, call counts |
+| `agents.parquet` | persona, model, degree per agent |
+| `opinions.parquet` | per day and agent: self-reported belief, scorer rating, opinion used |
+| `metrics.parquet` | per day: polarization, global disagreement, neighbour correlation, per-model means |
+| `events.jsonl` | per day and agent: feed, reasoning, post, memory, raw reply, errors; rewiring events |
+| `edges.jsonl` | the network on day 0 and on every day it changed |
+| `viewer.html` | written by `disensa viz`: one offline file with the viewer and data |
+
+## Layout
+
+```
+src/disensa/
+  config.py     typed YAML experiment configs (Pydantic)
+  networks.py   graphs and initial opinions
+  baselines.py  DeGroot, bounded confidence, Deffuant, Friedkin–Johnsen
+  metrics.py    polarization, global disagreement, neighbour correlation (Wang et al. §4.2)
+  personas.py   Wang-style personas
+  prompts.py    every prompt, in one place
+  llm.py        one async client for all providers (LiteLLM) + cache + JSON repair
+  fake_llm.py   deterministic offline backend
+  engine.py     the simulation loop
+  ensemble.py   model assignment
+  rewiring.py   unfollow/follow dynamics
+  analysis.py   timelines, opinion shifts, per-model summaries, change points
+  numeric.py    numeric baselines in the run format
+  export.py     run → viewer data / offline viewer file
+  app.py        local web app server
+  static/       the app page + vendored d3
+  cli.py        `disensa` command
+```
+
+## Roadmap
+
+- [x] M0 skeleton, configs, LLM client
+- [x] M1 networks, numeric baselines, metrics
+- [x] M2 LLM agents, Wang et al. loop, scorer
+- [x] M3 multi-model ensemble
+- [x] M4 rewiring
+- [x] M5 individual trajectory tooling
+- [x] M7 d3 viewer
+- [x] Web app: configure, run and watch simulations live
+- [ ] M6 INDACO: vLLM + SLURM sweeps (point `api_base` at a vLLM server)

disensa-0.1.0/README.md

@@ -0,0 +1,126 @@
+# disensa
+
+Opinion dynamics with LLM agents on social networks, where different agents can run on
+**different language models**. It extends the Social Simulation Framework of Wang et al.
+(COLING 2025, arXiv:2409.19338), which used one LLM for every agent, with:
+
+- a **multi-model ensemble**: each agent's reasoning comes from a model you choose
+  (Claude, GPT, Grok, DeepSeek, Llama, Gemma, Mistral, Qwen, …);
+- **individual-level inspection**: every agent's reading, reasoning and posts are logged, so
+  you can trace how and why a single agent moved;
+- **network rewiring** (optional): agents unfollow people they disagree with;
+- an **interactive d3 viewer** for every run.
+
+## Setup
+
+```bash
+uv sync --extra analysis     # dependencies incl. analysis tools
+cp .env.example .env         # only if you use paid APIs
+```
+
+For free local models, install [Ollama](https://ollama.com) and pull a few:
+
+```bash
+ollama pull llama3.2:3b && ollama pull llama3.1:8b && ollama pull qwen2.5:7b
+OLLAMA_NUM_PARALLEL=4 OLLAMA_MAX_LOADED_MODELS=3 ollama serve
+uv run disensa ping ollama_chat/llama3.2:3b      # check it answers
+```
+
+## The app
+
+```bash
+uv run disensa app          # opens http://127.0.0.1:8765
+```
+
+The start page (a swarm of agents that scatters from your cursor) leads to the lab at `/lab`.
+
+Pick a preset or set everything by hand (engine, topology, initial opinions, models,
+recommender, rewiring, numeric algorithm), press **Run simulation**, and watch it live.
+Nodes are shaded from pale blue (oppose) to deep blue (support) and drift left to right with
+their opinion, so camps separate on screen. The **Runs** tab lists past runs to replay.
+Start with the `demo_camps` preset: offline, a few seconds.
+
+## Command line
+
+```bash
+uv run disensa run configs/demo_fake.yaml        # offline fake models, a few seconds
+uv run disensa run configs/quick.yaml            # 10 agents, 5 days, Ollama, a few minutes
+uv run disensa inspect runs/<run_dir>            # per-model behaviour + largest opinion shifts
+uv run disensa inspect runs/<run_dir> --agent 3  # one agent's day-by-day story
+uv run disensa viz runs/<run_dir>                # open the interactive viewer
+```
+
+| Config | What it is |
+|---|---|
+| `demo_camps.yaml` | Offline demo where the population splits into camps |
+| `demo_fake.yaml`, `demo_fake_rewiring.yaml` | Offline demos (fake models); try the whole pipeline for free |
+| `numeric_bc.yaml` | Classic bounded confidence, opens in the app like any run |
+| `quick.yaml` | Smallest real run on Ollama, for checking prompts |
+| `wang/{small_world,scale_free,random}.yaml` | Wang et al. replication, one model, 50 agents × 30 days |
+| `mixed_local.yaml` | Three open-weight models from three labs, on Ollama |
+| `mixed_api.yaml` | Claude, GPT, Grok, DeepSeek through their APIs (paid) |
+| `bc_small_world.yaml`, `fj_scale_free.yaml` | Numeric baselines (`disensa baseline`) |
+
+`--days N` overrides the number of days for a quick try.
+
+## How a run works
+
+1. **Network**: Erdős–Rényi, Watts–Strogatz or Barabási–Albert, seeded.
+2. **Agents**: each gets a persona (gender, age, education, Big Five poles, initial
+   opinion on [-2, 2]) and a model (`assignment`: balanced, random, or clustered by community).
+3. **Day 0**: every agent writes a first post about the topic.
+4. **Each day**: an agent reads a few posts from its neighbours (optionally only those
+   within the recommender threshold), then returns its reasoning, new belief, new post and an
+   updated memory in one call. A fixed scorer model rates every post on [-2, 2].
+5. **End of day**: optional rewiring; metrics are recorded.
+
+Everything is cached on disk, so re-running the same config costs nothing.
+
+## Run outputs
+
+`runs/<timestamp>_<name>_s<seed>/`
+
+| File | Contents |
+|---|---|
+| `meta.json` | config, git commit, timing, call counts |
+| `agents.parquet` | persona, model, degree per agent |
+| `opinions.parquet` | per day and agent: self-reported belief, scorer rating, opinion used |
+| `metrics.parquet` | per day: polarization, global disagreement, neighbour correlation, per-model means |
+| `events.jsonl` | per day and agent: feed, reasoning, post, memory, raw reply, errors; rewiring events |
+| `edges.jsonl` | the network on day 0 and on every day it changed |
+| `viewer.html` | written by `disensa viz`: one offline file with the viewer and data |
+
+## Layout
+
+```
+src/disensa/
+  config.py     typed YAML experiment configs (Pydantic)
+  networks.py   graphs and initial opinions
+  baselines.py  DeGroot, bounded confidence, Deffuant, Friedkin–Johnsen
+  metrics.py    polarization, global disagreement, neighbour correlation (Wang et al. §4.2)
+  personas.py   Wang-style personas
+  prompts.py    every prompt, in one place
+  llm.py        one async client for all providers (LiteLLM) + cache + JSON repair
+  fake_llm.py   deterministic offline backend
+  engine.py     the simulation loop
+  ensemble.py   model assignment
+  rewiring.py   unfollow/follow dynamics
+  analysis.py   timelines, opinion shifts, per-model summaries, change points
+  numeric.py    numeric baselines in the run format
+  export.py     run → viewer data / offline viewer file
+  app.py        local web app server
+  static/       the app page + vendored d3
+  cli.py        `disensa` command
+```
+
+## Roadmap
+
+- [x] M0 skeleton, configs, LLM client
+- [x] M1 networks, numeric baselines, metrics
+- [x] M2 LLM agents, Wang et al. loop, scorer
+- [x] M3 multi-model ensemble
+- [x] M4 rewiring
+- [x] M5 individual trajectory tooling
+- [x] M7 d3 viewer
+- [x] Web app: configure, run and watch simulations live
+- [ ] M6 INDACO: vLLM + SLURM sweeps (point `api_base` at a vLLM server)

disensa-0.1.0/configs/bc_small_world.yaml

@@ -0,0 +1,14 @@
+name: bc_small_world
+seed: 42
+network:
+  topology: watts_strogatz
+  n: 50
+  k: 6
+  beta: 0.1
+opinions:
+  distribution: uniform
+baseline:
+  model: bounded_confidence
+  steps: 100
+  epsilon: 1.0
+  mu: 0.5

disensa-0.1.0/configs/demo_camps.yaml

@@ -0,0 +1,22 @@
+# Offline demo where the population splits into camps (fake models, a few seconds).
+# Tribal agents only listen to people within 0.7 of their view; the recommender hides
+# distant neighbours; rewiring lets agents unfollow people they disagree with.
+name: demo_camps
+seed: 3
+network: {topology: watts_strogatz, n: 60, k: 6, beta: 0.15}
+opinions: {distribution: uniform}
+topic:
+  name: euthanasia
+  statement: Euthanasia should be legal for terminally ill adults who clearly request it.
+simulation:
+  days: 25
+  feed: {min_posts: 2, max_posts: 5}
+  recommender: {enabled: true, threshold: 1.5}
+  rewiring: {enabled: true, probability: 0.25, unfollow_threshold: 1.0, follow: similar, follow_threshold: 0.5}
+assignment: balanced
+models:
+  - {name: fake/tribal, weight: 3}
+  - {name: fake/stubborn, weight: 1}
+scorer:
+  name: fake/scorer
+llm: {max_concurrency: 64}

disensa-0.1.0/configs/demo_fake.yaml

@@ -0,0 +1,17 @@
+# Offline demo with the fake backend: no model needed, runs in seconds.
+# Useful to try the pipeline, the trajectory tools and the visualization.
+name: demo_fake
+seed: 7
+network: {topology: watts_strogatz, n: 60, k: 6, beta: 0.1}
+opinions: {distribution: uniform}
+simulation:
+  days: 30
+  feed: {min_posts: 2, max_posts: 5}
+  recommender: {enabled: false}
+models:
+  - {name: fake/bounded, weight: 2}
+  - {name: fake/conformist, weight: 1}
+  - {name: fake/stubborn, weight: 1}
+scorer:
+  name: fake/scorer
+llm: {max_concurrency: 64}

disensa-0.1.0/configs/demo_fake_rewiring.yaml

@@ -0,0 +1,18 @@
+# Offline demo with rewiring: agents unfollow people they disagree with.
+name: demo_fake_rewiring
+seed: 7
+network: {topology: watts_strogatz, n: 60, k: 6, beta: 0.1}
+opinions: {distribution: uniform}
+simulation:
+  days: 30
+  feed: {min_posts: 2, max_posts: 5}
+  recommender: {enabled: false}
+  rewiring: {enabled: true, probability: 0.2, unfollow_threshold: 1.2, follow: similar, follow_threshold: 0.5}
+assignment: clustered
+models:
+  - {name: fake/bounded, weight: 2}
+  - {name: fake/conformist, weight: 1}
+  - {name: fake/stubborn, weight: 1}
+scorer:
+  name: fake/scorer
+llm: {max_concurrency: 64}

disensa-0.1.0/configs/fj_scale_free.yaml

@@ -0,0 +1,14 @@
+name: fj_scale_free
+seed: 42
+network:
+  topology: barabasi_albert
+  n: 50
+  m: 3
+opinions:
+  distribution: bimodal
+  mean: 1.2
+  std: 0.4
+baseline:
+  model: friedkin_johnsen
+  steps: 100
+  stubbornness: 1.0

disensa-0.1.0/configs/mixed_api.yaml

@@ -0,0 +1,24 @@
+# Multi-model ensemble through APIs (costs money). Put keys in .env first:
+# ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, DEEPSEEK_API_KEY
+# Model names change often: check each provider's current model list before running.
+name: mixed_api
+seed: 1
+network: {topology: watts_strogatz, n: 20, k: 4, beta: 0.1}
+opinions: {distribution: uniform}
+topic:
+  name: euthanasia
+  statement: Euthanasia should be legal for terminally ill adults who clearly request it.
+simulation:
+  days: 10
+  feed: {min_posts: 1, max_posts: 4}
+  recommender: {enabled: true, threshold: 2.0}
+  opinion_source: self
+assignment: balanced
+models:
+  - {name: anthropic/claude-haiku-4-5}
+  - {name: openai/gpt-4o-mini}
+  - {name: xai/grok-3-mini}
+  - {name: deepseek/deepseek-chat}
+scorer:
+  name: ollama_chat/qwen2.5:7b   # scorer stays local and outside the agents' labs
+llm: {max_concurrency: 4}

disensa-0.1.0/configs/mixed_local.yaml

@@ -0,0 +1,23 @@
+# Multi-model ensemble on your Mac: three open-weight models from three labs, 20 agents.
+# Pull first:  ollama pull llama3.1:8b && ollama pull gemma2:9b && ollama pull mistral:7b && ollama pull qwen2.5:7b
+# Start with:  OLLAMA_NUM_PARALLEL=4 OLLAMA_MAX_LOADED_MODELS=4 ollama serve
+name: mixed_local
+seed: 1
+network: {topology: watts_strogatz, n: 20, k: 4, beta: 0.1}
+opinions: {distribution: uniform}
+topic:
+  name: euthanasia
+  statement: Euthanasia should be legal for terminally ill adults who clearly request it.
+simulation:
+  days: 10
+  feed: {min_posts: 1, max_posts: 4}
+  recommender: {enabled: true, threshold: 2.0}
+  opinion_source: self
+assignment: balanced   # balanced | random | clustered
+models:
+  - {name: ollama_chat/llama3.1:8b}   # Meta
+  - {name: ollama_chat/gemma2:9b}     # Google
+  - {name: ollama_chat/mistral:7b}    # Mistral
+scorer:
+  name: ollama_chat/qwen2.5:7b        # Alibaba: a lab none of the agents come from
+llm: {max_concurrency: 4}

disensa-0.1.0/configs/numeric_bc.yaml

@@ -0,0 +1,6 @@
+# Classic bounded confidence (Hegselmann–Krause) on a small world: narrow confidence -> clusters.
+name: numeric_bc
+seed: 3
+network: {topology: watts_strogatz, n: 60, k: 6, beta: 0.15}
+opinions: {distribution: uniform}
+baseline: {model: bounded_confidence, steps: 40, epsilon: 0.7, mu: 0.5}

disensa-0.1.0/configs/quick.yaml

@@ -0,0 +1,18 @@
+# Fast local check: 10 agents, 5 days, small model. A few minutes on an M3 Pro.
+name: quick
+seed: 1
+network: {topology: watts_strogatz, n: 10, k: 4, beta: 0.1}
+opinions: {distribution: uniform}
+topic:
+  name: euthanasia
+  statement: Euthanasia should be legal for terminally ill adults who clearly request it.
+simulation:
+  days: 5
+  feed: {min_posts: 1, max_posts: 3}
+  recommender: {enabled: true, threshold: 2.0}
+  opinion_source: self
+models:
+  - name: ollama_chat/llama3.2:3b
+scorer:
+  name: ollama_chat/qwen2.5:7b
+llm: {max_concurrency: 4}

disensa-0.1.0/configs/wang/random.yaml

@@ -0,0 +1,19 @@
+# Wang et al. (2025) replication, single model: 50 agents, 30 days, recommender on.
+# Roughly 3,000 agent calls + 1,500 scorer calls: run overnight locally, or on a server.
+name: wang_random
+seed: 42
+network: {topology: erdos_renyi, n: 50, p: 0.12}
+opinions: {distribution: uniform}
+topic:
+  name: euthanasia
+  statement: Euthanasia should be legal for terminally ill adults who clearly request it.
+simulation:
+  days: 30
+  feed: {min_posts: 1, max_posts: 5}
+  recommender: {enabled: true, threshold: 2.0}
+  opinion_source: self
+models:
+  - name: ollama_chat/llama3.1:8b
+scorer:
+  name: ollama_chat/qwen2.5:7b
+llm: {max_concurrency: 4}

disensa-0.1.0/configs/wang/scale_free.yaml

@@ -0,0 +1,19 @@
+# Wang et al. (2025) replication, single model: 50 agents, 30 days, recommender on.
+# Roughly 3,000 agent calls + 1,500 scorer calls: run overnight locally, or on a server.
+name: wang_scale_free
+seed: 42
+network: {topology: barabasi_albert, n: 50, m: 3}
+opinions: {distribution: uniform}
+topic:
+  name: euthanasia
+  statement: Euthanasia should be legal for terminally ill adults who clearly request it.
+simulation:
+  days: 30
+  feed: {min_posts: 1, max_posts: 5}
+  recommender: {enabled: true, threshold: 2.0}
+  opinion_source: self
+models:
+  - name: ollama_chat/llama3.1:8b
+scorer:
+  name: ollama_chat/qwen2.5:7b
+llm: {max_concurrency: 4}

disensa-0.1.0/configs/wang/small_world.yaml

@@ -0,0 +1,19 @@
+# Wang et al. (2025) replication, single model: 50 agents, 30 days, recommender on.
+# Roughly 3,000 agent calls + 1,500 scorer calls: run overnight locally, or on a server.
+name: wang_small_world
+seed: 42
+network: {topology: watts_strogatz, n: 50, k: 6, beta: 0.1}
+opinions: {distribution: uniform}
+topic:
+  name: euthanasia
+  statement: Euthanasia should be legal for terminally ill adults who clearly request it.
+simulation:
+  days: 30
+  feed: {min_posts: 1, max_posts: 5}
+  recommender: {enabled: true, threshold: 2.0}
+  opinion_source: self
+models:
+  - name: ollama_chat/llama3.1:8b
+scorer:
+  name: ollama_chat/qwen2.5:7b
+llm: {max_concurrency: 4}

disensa-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "disensa"
+version = "0.1.0"
+description = "Multi-model LLM-agent opinion dynamics on social networks"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Theo Radicella" }]
+license = { text = "MIT" }
+dependencies = [
+    "pydantic>=2.7",
+    "pyyaml>=6.0",
+    "typer>=0.12",
+    "numpy>=1.26",
+    "networkx>=3.2",
+    "pandas>=2.2",
+    "pyarrow>=15",
+    "litellm>=1.40",
+    "diskcache>=5.6",
+    "tenacity>=8.2",
+    "python-dotenv>=1.0",
+]
+
+[project.urls]
+Repository = "https://github.com/theoradicella/disensa"
+
+[project.optional-dependencies]
+analysis = [
+    "duckdb>=1.0",
+    "scipy>=1.12",
+    "statsmodels>=0.14",
+    "ruptures>=1.1",
+    "matplotlib>=3.8",
+    "seaborn>=0.13",
+    "scikit-learn>=1.4",
+]
+
+[project.scripts]
+disensa = "disensa.cli:app"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "ruff>=0.5"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/disensa"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/disensa/prompts.py" = ["E501"]  # prompt templates are quoted verbatim
+"tests/*" = ["E501"]

disensa-0.1.0/src/disensa/__init__.py

@@ -0,0 +1,7 @@
+"""disensa: multi-model LLM-agent opinion dynamics on social networks."""
+
+__version__ = "0.1.0"
+
+# Opinion scale shared by every component (Wang et al. 2025 use [-2, 2]).
+OPINION_MIN = -2.0
+OPINION_MAX = 2.0