![Montelago Explorer](banner.png)
# Montelago Explorer

**An interactive browser for a synthetic population experiment on institutional trust.**

### 🔗 [Open the live explorer](https://mirko-degli-esposti.github.io/montelago-explorer/)

> ⚠️ **Note on language:** The simulation is conducted entirely in Italian. Agent profiles, municipal communications, survey responses, and open-ended motivations are all in Italian — this is by design, as the experiment models Italian civic culture and the specific register of Italian municipal communication. This README is in English for accessibility; the interface itself is not.

---

## What is this?

Montelago is a fictional Italian municipality. Its 120 inhabitants do not exist.

They are **synthetic personas** generated by a large language model (DeepSeek), designed to study how citizens with different levels of institutional trust respond to official municipal communications about a water infrastructure project. Each citizen has a name, an age, a job, a life history, and a latent attitude toward local government — and reacts to seven different types of official messages.

This is the **Synthetic Instrument Validation Experiment (SIVE)** — a controlled within-subjects simulation designed to characterize the controllability of an LLM-driven synthetic population as a scientific instrument, before that instrument is used to study any real population.

The key question is not *"do synthetic citizens behave like real citizens?"* That is a problem of external validity, and a separate, harder one. The question here is more basic: **can an LLM-generated population function as a measurable, controllable instrument?** Can it encode known attitudes, respond to stimuli of known valence, and do so in a replicable, group-ordered way?

The logic is analogous to laboratory physics: before using an instrument to study a complex natural system, you first characterize its response function under controlled conditions, on sources of known intensity.

[![arXiv](https://img.shields.io/badge/arXiv-2607.00910v1-b31b1b.svg)](https://arxiv.org/abs/2607.00910)

*(arXiv link to follow — paper submitted, preprint forthcoming)*

---

## The experimental design

**Population:** 120 synthetic agents, balanced by age, gender, and education, divided into three equal groups by latent institutional trust (`fiducia_istituzione`, 1–10 scale):

| Group | N  | Latent trust range | Profile type |
|-------|----|--------------------|--------------|
| LOW   | 40 | 1–3                | Skeptical or distrustful of municipal institutions |
| MED   | 40 | 4–6                | Ambivalent, conditionally trusting |
| HIGH  | 40 | 7–10               | Consistently trusting, positive prior experience |

**Design:** Within-subjects — each agent processes all seven conditions independently, with a full reset between conditions (no memory carried across them).

**Seven experimental conditions**, all concerning the same municipal water network, to keep the design strictly unidimensional:

| Code    | Description | Expected effect |
|---------|-------------|-----------------|
| `POS`   | Strong positive communication (full pipe replacement, EU funding, daily monitoring, full transparency) | Trust ↑↑ |
| `POS2`  | Exact replica of POS | POS ≈ POS2 (noise-floor estimation) |
| `POSW`  | Originally designed as weak positive (vague, no timeline) | *Post hoc* found to behave as functionally negative — see below |
| `POSW2` | Recalibrated weak positive (concrete, low-affect, no admission of inaction) | Small trust ↑ |
| `NEG`   | Negative communication (repeated failures, water quality alert, no repair funds) | Trust ↓↓ |
| `PLA`   | Inert placebo (neighborhood festival announcement, thematically orthogonal) | ≈ 0 |
| `CTRL`  | No message, survey only | ≈ 0 |

**A central finding of the experiment**: POSW, designed to read as mildly reassuring, was measured by the instrument as functionally negative — the text combined an unresolved problem, no timeline, and institutional passivity, a pattern a distrustful audience reads as confirmation of its skepticism rather than as reassurance. POSW2 was written to repair exactly these two defects while remaining a deliberately low-intensity message, and restored the expected ordering. We treat this not as a design error but as the clearest demonstration of what instrument characterization is for.

**Measurement instrument (per condition):**
- PRE survey: institutional trust (1–10), source credibility (1–10), perceived information adequacy (1–10), emotion (categorical, 5 options), behavioral intention (categorical, 5 options)
- 3 free-text reaction steps to the message, at fixed temporal markers (immediate, a couple of hours later, end of day)
- POST survey: same items

**Validation criteria (C1–C7):**
1. **C1 — Fidelity**: do agents preserve the attitudes encoded in their profiles? (LOW < MED < HIGH baseline trust)
2. **C2 — Stability**: are baseline (PRE) measurements consistent across conditions, before any stimulus is delivered?
3. **C3 — Noise floor**: how much does POS vs POS2 vary intrinsically, and what is the instrument's true measurement resolution?
4. **C4 — Specificity**: is the thematically orthogonal placebo (PLA) genuinely inert relative to CTRL?
5. **C5 — Sensitivity**: are the seven conditions ordered consistently with their known or measured valence?
6. **C6 — Ordering**: does the observed condition ranking match the expected ranking (Kendall's τ)?
7. **C7 — Receipt check**: do agents register having received *any* on-topic communication at all, regardless of its valence?

All seven criteria pass at every temperature tested ($t \in \{0.2, 0.5, 0.7\}$).

---

## Technical setup

- **LLM backend:** `deepseek/deepseek-chat` via OpenRouter
- **Temperature:** this explorer shows the $t=0.2$ run, adopted as the paper's reference configuration; the full temperature sweep ($t \in \{0.2, 0.5, 0.7\}$) is reported in the paper and in the analysis notebook, not in this interface
- **Harness:** custom minimal harness (`sive_harness.ipynb`) — direct `openai.AsyncOpenAI` client against the OpenRouter endpoint, no agentic loop, no router/cache layer, fixed 13 calls/agent/condition (5 PRE + 3 reactions + 5 POST)
- **Checkpointing:** incremental, Google Drive, after every completed condition
- **Population generation:** MaxEnt / GibbsPCD synthetic population synthesis

---

## How to use this explorer

The interface (`index.html`) loads agent data from `agents_data.js`, which must be in the same folder. Open `index.html` in any browser — no server required.

**Navigation:**
- Filter agents by trust group (LOW / MED / HIGH) or search by name, persona, or occupation
- Click an agent to open their dossier
- Switch between experimental conditions using the tabs
- Each condition shows: the official communication received → PRE/POST measurements → emotion and intention → reaction steps

---

## Related work

This experiment is part of a broader research program on **Generative Synthetic Populations (GSP)** at the [City Science Laboratory](https://physycom.github.io/) of the Department of Physics and Astronomy, University of Bologna.

The population synthesis methodology (MaxEnt / GibbsPCD) is described in:

> Degli Esposti M. (2026). *Scalable Maximum Entropy Population Synthesis via Persistent Contrastive Divergence.* [arXiv preprint](https://arxiv.org/abs/2603.27312)

The instrument characterization experiment (SIVE) described here is reported in:

> Degli Esposti M. (2026). *Calibrating the Instrument: Controllability of an LLM-Driven Synthetic Population.* Manuscript submitted to the *Journal of Artificial Societies and Social Simulation (JASSS)*. [arXiv preprint](#) — link to follow.

---

## Repository structure

```
montelago-explorer/
├── index.html                          # Interactive browser (self-contained)
├── agents_data.js                      # Generated from survey_FINAL.csv + reactions_FINAL.csv
├── sive_120_completi.json              # Synthetic population: 120 agent profiles
├── sive_harness.ipynb                  # Data collection: seven-condition campaign
├── sive_c3_noise_subexperiment.ipynb   # Single-profile noise sub-experiment (instrument noise floor)
├── sive_temperature_analysis_v4.ipynb  # Validation criteria (C1–C7), temperature sweep, figures
└── README.md                           # This file
```

`agents_data.js` is regenerated after each experimental run using `sive_to_web.py` (see the [main research repository](https://github.com/mirko-degli-esposti/maxent-popsynth-pcd)).

---

## Author

**Mirko Degli Esposti**
Full Professor of Mathematical Physics
Department of Physics and Astronomy / City Science Lab
University of Bologna

---

*Montelago does not exist. Its inhabitants are synthetic. The experiment is real.*