disensa 0.1.0__py3-none-any.whl

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

disensa/analysis.py

@@ -0,0 +1,198 @@
+"""Individual-level inspection of a finished run.
+
+Everything an agent read, thought and wrote is in the run folder; this module turns it into
+tables you can reason about:
+
+  load_run(path)             everything in one object
+  agent_timeline(run, i)     day-by-day story of one agent: what it read, its reasoning, post
+  opinion_shifts(run)        every notable change of opinion, with what the agent had just read
+                             and whether it moved toward it (assimilation) or away (repulsion)
+  model_summary(run)         the same numbers aggregated per LLM
+  change_points(series)      days where an agent's opinion trajectory changes regime
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import networkx as nx
+import numpy as np
+import pandas as pd
+
+
+@dataclass
+class RunData:
+    path: Path
+    meta: dict
+    agents: pd.DataFrame  # one row per agent
+    opinions: pd.DataFrame  # (day, agent) -> belief, score, opinion
+    metrics: pd.DataFrame  # one row per day
+    posts: pd.DataFrame  # (day, agent) -> feed, reasoning, post, memory, error, ...
+    rewires: pd.DataFrame  # (day, agent, dropped, added)
+    edge_snapshots: list[tuple[int, list[tuple[int, int]]]]
+
+    @property
+    def days(self) -> int:
+        return int(self.opinions["day"].max())
+
+    def opinion_matrix(self) -> np.ndarray:
+        """Array of shape (days + 1, n_agents)."""
+        return self.opinions.pivot(index="day", columns="agent", values="opinion").to_numpy()
+
+    def graph_at(self, day: int) -> nx.Graph:
+        """The network as it was at the end of `day` (after that day's rewiring)."""
+        edges = next(e for d, e in reversed(self.edge_snapshots) if d <= day)
+        g = nx.Graph()
+        g.add_nodes_from(self.agents["agent"])
+        g.add_edges_from(edges)
+        return g
+
+
+def load_run(path: str | Path) -> RunData:
+    path = Path(path)
+    events = []
+    for line in open(path / "events.jsonl", encoding="utf-8"):
+        try:
+            events.append(json.loads(line))
+        except json.JSONDecodeError:  # a run still in progress may end mid-line
+            break
+    posts = pd.DataFrame([e for e in events if e.get("type", "post") == "post"])
+    rewires = pd.DataFrame(
+        [e for e in events if e.get("type") == "rewire"],
+        columns=["day", "type", "agent", "dropped", "added"],
+    )
+    snapshots = []
+    for line in open(path / "edges.jsonl", encoding="utf-8"):
+        try:
+            s = json.loads(line)
+        except json.JSONDecodeError:
+            break
+        snapshots.append((s["day"], [tuple(e) for e in s["edges"]]))
+    return RunData(
+        path=path,
+        meta=json.loads((path / "meta.json").read_text()),
+        agents=pd.read_parquet(path / "agents.parquet"),
+        opinions=pd.read_parquet(path / "opinions.parquet"),
+        metrics=pd.read_parquet(path / "metrics.parquet"),
+        posts=posts,
+        rewires=rewires,
+        edge_snapshots=sorted(snapshots, key=lambda s: s[0]),
+    )
+
+
+def _feed_authors(feed) -> list[int]:
+    return [int(f["author"]) for f in (feed or [])]
+
+
+def agent_timeline(run: RunData, agent: int) -> pd.DataFrame:
+    """One row per day for `agent`, with the mean opinion (on the previous day) of what it read."""
+    ops = run.opinion_matrix()
+    p = run.posts[run.posts["agent"] == agent].sort_values("day")
+    rows = []
+    for _, r in p.iterrows():
+        d = int(r["day"])
+        authors = _feed_authors(r["feed"])
+        feed_mean = float(np.mean(ops[d - 1, authors])) if authors and d > 0 else np.nan
+        rows.append(
+            {
+                "day": d,
+                "opinion": ops[d, agent],
+                "belief": r["belief"],
+                "score": r["score"],
+                "read_from": authors,
+                "feed_mean": feed_mean,
+                "reasoning": r["reasoning"],
+                "post": r["post"],
+                "error": r["error"],
+            }
+        )
+    return pd.DataFrame(rows)
+
+
+def opinion_shifts(run: RunData, min_delta: float = 0.5) -> pd.DataFrame:
+    """Every day-to-day change of at least `min_delta`, with its context.
+
+    direction:
+      toward  moved in the direction of the average post it read (assimilation)
+      away    moved against it (repulsion / backfire)
+      none    read nothing, or what it read matched its old opinion
+    """
+    ops = run.opinion_matrix()
+    model = dict(zip(run.agents["agent"], run.agents["model"], strict=True))
+    rows = []
+    for _, r in run.posts[run.posts["day"] > 0].iterrows():
+        d, i = int(r["day"]), int(r["agent"])
+        before, after = ops[d - 1, i], ops[d, i]
+        delta = after - before
+        if abs(delta) < min_delta:
+            continue
+        authors = _feed_authors(r["feed"])
+        feed_mean = float(np.mean(ops[d - 1, authors])) if authors else np.nan
+        pull = feed_mean - before if authors else 0.0
+        if not authors or abs(pull) < 1e-9:
+            direction = "none"
+        else:
+            direction = "toward" if np.sign(delta) == np.sign(pull) else "away"
+        rows.append(
+            {
+                "day": d,
+                "agent": i,
+                "model": model[i],
+                "before": before,
+                "after": after,
+                "delta": delta,
+                "n_read": len(authors),
+                "feed_mean": feed_mean,
+                "direction": direction,
+                "read_from": authors,
+                "reasoning": r["reasoning"],
+            }
+        )
+    cols = ["day", "agent", "model", "before", "after", "delta", "n_read", "feed_mean"]
+    cols += ["direction", "read_from", "reasoning"]
+    return pd.DataFrame(rows, columns=cols)
+
+
+def model_summary(run: RunData, min_delta: float = 0.5) -> pd.DataFrame:
+    """Per-model behaviour: how much agents move, in which direction, and how often they fail."""
+    ops = run.opinion_matrix()
+    steps = np.abs(np.diff(ops, axis=0))  # (days, agents)
+    shifts = opinion_shifts(run, min_delta)
+    errors = run.posts.assign(err=run.posts["error"].notna()).groupby("model")["err"].mean()
+    rows = []
+    for m, group in run.agents.groupby("model"):
+        idx = group["agent"].to_numpy()
+        s = shifts[shifts["model"] == m]
+        rows.append(
+            {
+                "model": m,
+                "agents": len(idx),
+                "initial_mean": float(ops[0, idx].mean()),
+                "final_mean": float(ops[-1, idx].mean()),
+                "mean_abs_daily_change": float(steps[:, idx].mean()) if len(steps) else 0.0,
+                "shifts": len(s),
+                "toward_share": float((s["direction"] == "toward").mean()) if len(s) else np.nan,
+                "away_share": float((s["direction"] == "away").mean()) if len(s) else np.nan,
+                "error_rate": float(errors.get(m, 0.0)),
+            }
+        )
+    return pd.DataFrame(rows)
+
+
+def change_points(series: np.ndarray, penalty: float = 1.0) -> list[int]:
+    """Days where the trajectory changes regime.
+
+    Uses PELT from `ruptures` when installed (`uv sync --extra analysis`); otherwise falls
+    back to days whose absolute change exceeds `penalty`.
+    """
+    x = np.asarray(series, dtype=float)
+    if len(x) < 3:
+        return []
+    try:
+        import ruptures as rpt
+    except ImportError:
+        return [int(d) for d in np.flatnonzero(np.abs(np.diff(x)) >= penalty) + 1]
+    breaks = rpt.Pelt(model="l2", min_size=1, jump=1).fit(x.reshape(-1, 1)).predict(pen=penalty)
+    return [int(b) for b in breaks if b < len(x)]

disensa/app.py

@@ -0,0 +1,340 @@
+"""`disensa app`: a local web app to configure, run and watch simulations.
+
+A small standard-library HTTP server bound to 127.0.0.1. It serves one page (static/app.html)
+a landing page at / and the lab at /lab, plus a JSON API:
+
+  GET  /                       landing page (static/landing.html)
+  GET  /lab                    the lab: configure, run, watch (static/app.html)
+  GET  /docs                   documentation (static/docs.html)
+  GET  /api/options              topologies, algorithms, installed Ollama models, presets
+  GET  /api/runs                 past and running runs, newest first
+  POST /api/runs                 {"engine": "llm"|"numeric", "config": {...}} -> {"id": ...}
+  GET  /api/runs/<id>            the run's data for the viewer (works while it is running)
+  GET  /api/runs/<id>/status     {"status", "day", "days", "error"}
+  POST /api/runs/<id>/cancel     stop a running simulation after the current day
+
+Each run executes in its own thread with its own asyncio loop, writing the usual run folder.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+import time
+import traceback
+import urllib.request
+import webbrowser
+from dataclasses import dataclass, field
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib import resources
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from disensa.config import ExperimentConfig
+from disensa.fake_llm import BEHAVIOURS
+
+OLLAMA_URL = "http://localhost:11434"
+STATIC = resources.files("disensa").joinpath("static")
+
+
+@dataclass
+class Job:
+    id: str
+    run_dir: Path
+    engine: str
+    days: int
+    status: str = "running"  # running | done | failed | cancelled
+    day: int = -1
+    error: str | None = None
+    started: float = field(default_factory=time.time)
+    loop: asyncio.AbstractEventLoop | None = None
+    task: asyncio.Task | None = None
+
+
+class RunManager:
+    def __init__(self, runs_root: Path):
+        self.runs_root = runs_root
+        self.jobs: dict[str, Job] = {}
+        self.lock = threading.Lock()
+
+    # ------------------------------------------------------------------ starting runs
+
+    def start(self, engine: str, raw: dict) -> Job:
+        from disensa.runs import new_run_dir
+
+        raw = dict(raw)
+        raw["output_dir"] = str(self.runs_root)
+        if engine == "numeric":
+            raw.pop("models", None)
+            raw.pop("scorer", None)
+        cfg = ExperimentConfig.model_validate(raw)
+        if engine == "llm" and not cfg.models:
+            raise ValueError("pick at least one model")
+        if engine == "numeric" and cfg.baseline is None:
+            raise ValueError("pick a numeric algorithm")
+        days = cfg.baseline.steps if engine == "numeric" else cfg.simulation.days
+        run_dir = new_run_dir(cfg)
+        job = Job(id=run_dir.name, run_dir=run_dir, engine=engine, days=days)
+        with self.lock:
+            self.jobs[job.id] = job
+        target = self._run_numeric if engine == "numeric" else self._run_llm
+        threading.Thread(target=target, args=(job, cfg), daemon=True).start()
+        return job
+
+    def _progress(self, job: Job):
+        def cb(day: int, _metrics: dict) -> None:
+            job.day = day
+
+        return cb
+
+    def _run_numeric(self, job: Job, cfg: ExperimentConfig) -> None:
+        from disensa.numeric import run_numeric
+
+        try:
+            run_numeric(cfg, run_dir=job.run_dir, progress=self._progress(job))
+            job.status = "done"
+        except Exception as e:
+            job.status, job.error = "failed", f"{type(e).__name__}: {e}"
+
+    def _run_llm(self, job: Job, cfg: ExperimentConfig) -> None:
+        from disensa.engine import Simulation
+        from disensa.runs import RunWriter, update_meta
+
+        loop = asyncio.new_event_loop()
+        job.loop = loop
+        writer = RunWriter(job.run_dir)
+        t0 = time.time()
+        try:
+            sim = Simulation(cfg)
+            job.task = loop.create_task(sim.run(writer, self._progress(job)))
+            loop.run_until_complete(job.task)
+            job.status = "done"
+            update_meta(
+                job.run_dir,
+                finished=True,
+                seconds=round(time.time() - t0, 1),
+                llm_calls=sim.client.calls,
+                cache_hits=sim.client.cache_hits,
+            )
+        except asyncio.CancelledError:
+            job.status = "cancelled"
+            update_meta(job.run_dir, cancelled=True)
+        except Exception as e:
+            job.status, job.error = "failed", f"{type(e).__name__}: {e}"
+            traceback.print_exc()
+        finally:
+            writer.close()
+            loop.close()
+
+    def cancel(self, run_id: str) -> bool:
+        job = self.jobs.get(run_id)
+        if not job or job.status != "running" or not job.loop or not job.task:
+            return False
+        job.loop.call_soon_threadsafe(job.task.cancel)
+        return True
+
+    # ------------------------------------------------------------------ reading runs
+
+    def run_dir(self, run_id: str) -> Path | None:
+        if not run_id or "/" in run_id or "\\" in run_id or run_id.startswith("."):
+            return None
+        d = self.runs_root / run_id
+        return d if (d / "meta.json").exists() else None
+
+    def status(self, run_id: str) -> dict:
+        job = self.jobs.get(run_id)
+        if job:
+            return {"status": job.status, "day": job.day, "days": job.days, "error": job.error}
+        d = self.run_dir(run_id)
+        meta = json.loads((d / "meta.json").read_text()) if d else {}
+        status = (
+            "cancelled"
+            if meta.get("cancelled")
+            else ("done" if meta.get("finished") else "incomplete")
+        )
+        return {"status": status, "day": None, "days": None, "error": None}
+
+    def list(self) -> list[dict]:
+        if not self.runs_root.exists():
+            return []
+        out = []
+        for d in sorted(self.runs_root.iterdir(), reverse=True):
+            meta_path = d / "meta.json"
+            if not meta_path.exists() or not (d / "agents.parquet").exists():
+                continue
+            try:
+                meta = json.loads(meta_path.read_text())
+            except json.JSONDecodeError:
+                continue
+            cfg = meta.get("config", {})
+            engine = meta.get("engine") or (
+                "numeric" if cfg.get("baseline") and not cfg.get("models") else "llm"
+            )
+            out.append(
+                {
+                    "id": d.name,
+                    "name": cfg.get("name", d.name),
+                    "started": meta.get("started"),
+                    "engine": engine,
+                    "topology": cfg.get("network", {}).get("topology"),
+                    "n": cfg.get("network", {}).get("n"),
+                    "models": [m["name"] for m in cfg.get("models", [])]
+                    or ([f"numeric/{cfg['baseline']['model']}"] if cfg.get("baseline") else []),
+                    **self.status(d.name),
+                }
+            )
+        return out[:100]
+
+    def payload(self, run_id: str) -> dict | None:
+        from disensa.analysis import load_run
+        from disensa.export import build_payload
+
+        d = self.run_dir(run_id)
+        if d is None:
+            return None
+        try:
+            return build_payload(load_run(d))
+        except (FileNotFoundError, ValueError, KeyError, IndexError, StopIteration):
+            return None  # nothing written yet
+
+
+def ollama_models() -> tuple[list[str], str | None]:
+    try:
+        with urllib.request.urlopen(f"{OLLAMA_URL}/api/tags", timeout=1.5) as r:
+            tags = json.loads(r.read())
+        return sorted(f"ollama_chat/{m['name']}" for m in tags.get("models", [])), None
+    except Exception:
+        return [], "Ollama is not running (start it with `ollama serve`)."
+
+
+def presets(config_dir: Path) -> list[dict]:
+    out = []
+    if not config_dir.exists():
+        return out
+    for p in sorted(config_dir.rglob("*.yaml")):
+        try:
+            raw = yaml.safe_load(p.read_text())
+        except yaml.YAMLError:
+            continue
+        if not isinstance(raw, dict) or "network" not in raw:
+            continue
+        engine = "numeric" if raw.get("baseline") and not raw.get("models") else "llm"
+        out.append({"file": str(p.relative_to(config_dir)), "engine": engine, "config": raw})
+    return out
+
+
+def make_handler(manager: RunManager, config_dir: Path):
+    class Handler(BaseHTTPRequestHandler):
+        server_version = "disensa"
+
+        def log_message(self, fmt, *args):  # keep the terminal quiet
+            pass
+
+        def _send(self, code: int, body: bytes, ctype: str) -> None:
+            self.send_response(code)
+            self.send_header("Content-Type", ctype)
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            self.wfile.write(body)
+
+        def _json(self, obj, code: int = 200) -> None:
+            self._send(code, json.dumps(obj, allow_nan=False).encode(), "application/json")
+
+        def _error(self, code: int, msg: str) -> None:
+            self._json({"error": msg}, code)
+
+        def do_GET(self):  # noqa: N802
+            path = self.path.split("?", 1)[0]
+            pages = {
+                "/": "landing.html",
+                "/index.html": "landing.html",
+                "/lab": "app.html",
+                "/docs": "docs.html",
+            }
+            if path in pages:
+                html = STATIC.joinpath(pages[path]).read_text(encoding="utf-8")
+                return self._send(200, html.encode(), "text/html; charset=utf-8")
+            if path == "/d3.min.js":
+                return self._send(
+                    200, STATIC.joinpath("d3.min.js").read_bytes(), "text/javascript; charset=utf-8"
+                )
+            if path == "/api/options":
+                models, err = ollama_models()
+                return self._json(
+                    {
+                        "ollama_models": models,
+                        "ollama_error": err,
+                        "fake_models": [
+                            "fake/bounded",
+                            *(f"fake/{b}" for b in BEHAVIOURS),
+                            "fake/scorer",
+                        ],
+                        "presets": presets(config_dir),
+                    }
+                )
+            if path == "/api/runs":
+                return self._json(manager.list())
+            parts = path.strip("/").split("/")
+            if len(parts) >= 3 and parts[:2] == ["api", "runs"]:
+                run_id = parts[2]
+                if manager.run_dir(run_id) is None:
+                    return self._error(404, "run not found")
+                if len(parts) == 4 and parts[3] == "status":
+                    return self._json(manager.status(run_id))
+                if len(parts) == 3:
+                    return self._json(
+                        {"status": manager.status(run_id), "data": manager.payload(run_id)}
+                    )
+            self._error(404, "not found")
+
+        def do_POST(self):  # noqa: N802
+            path = self.path.split("?", 1)[0]
+            length = int(self.headers.get("Content-Length") or 0)
+            try:
+                body = json.loads(self.rfile.read(length) or b"{}")
+            except json.JSONDecodeError:
+                return self._error(400, "invalid JSON")
+            if path == "/api/runs":
+                try:
+                    job = manager.start(body.get("engine", "llm"), body.get("config", {}))
+                except ValidationError as e:
+                    msg = "; ".join(
+                        f"{'.'.join(str(p) for p in err['loc'])}: {err['msg']}"
+                        for err in e.errors()
+                    )
+                    return self._error(400, msg)
+                except (ValueError, TypeError) as e:
+                    return self._error(400, str(e))
+                return self._json({"id": job.id}, HTTPStatus.CREATED)
+            parts = path.strip("/").split("/")
+            if len(parts) == 4 and parts[:2] == ["api", "runs"] and parts[3] == "cancel":
+                return self._json({"cancelled": manager.cancel(parts[2])})
+            self._error(404, "not found")
+
+    return Handler
+
+
+def serve(
+    port: int = 8765,
+    runs_root: Path = Path("runs"),
+    config_dir: Path = Path("configs"),
+    open_browser: bool = True,
+) -> None:
+    runs_root.mkdir(parents=True, exist_ok=True)
+    manager = RunManager(runs_root)
+    server = ThreadingHTTPServer(("127.0.0.1", port), make_handler(manager, config_dir))
+    url = f"http://127.0.0.1:{port}/"
+    print(f"disensa app running at {url}  (Ctrl+C to stop)")
+    if open_browser:
+        threading.Timer(0.5, lambda: webbrowser.open(url)).start()
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()

disensa/baselines.py

@@ -0,0 +1,96 @@
+"""Classic numeric opinion-dynamics models on a graph.
+
+Each model is a function (g, x0, params, rng) -> trajectory array of shape (steps + 1, N).
+Opinions live on [OPINION_MIN, OPINION_MAX].
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import networkx as nx
+import numpy as np
+
+from disensa import OPINION_MAX, OPINION_MIN
+from disensa.config import BaselineConfig
+
+
+def _adjacency(g: nx.Graph) -> np.ndarray:
+    return nx.to_numpy_array(g, nodelist=range(g.number_of_nodes()))
+
+
+def degroot(g: nx.Graph, x0: np.ndarray, cfg: BaselineConfig, rng) -> np.ndarray:
+    """DeGroot (1974): everyone moves to the average of self + neighbours."""
+    a = _adjacency(g) + np.eye(len(x0))
+    w = a / a.sum(axis=1, keepdims=True)
+    traj = [x0.copy()]
+    for _ in range(cfg.steps):
+        traj.append(w @ traj[-1])
+    return np.array(traj)
+
+
+def bounded_confidence(g: nx.Graph, x0: np.ndarray, cfg: BaselineConfig, rng) -> np.ndarray:
+    """Synchronous bounded confidence on a graph, as in Wang et al. §3.4.
+
+    x_i(t) = x_i(t-1) + μ · mean_{j∈N(i), |x_i-x_j|≤ε} (x_j(t-1) - x_i(t-1))
+    (Hegselmann–Krause style averaging over all confident neighbours.)
+    """
+    a = _adjacency(g).astype(bool)
+    traj = [x0.copy()]
+    for _ in range(cfg.steps):
+        x = traj[-1]
+        diff = x[None, :] - x[:, None]  # diff[i, j] = x_j - x_i
+        confident = a & (np.abs(diff) <= cfg.epsilon)
+        counts = confident.sum(axis=1)
+        pull = np.where(counts > 0, (diff * confident).sum(axis=1) / np.maximum(counts, 1), 0.0)
+        traj.append(x + cfg.mu * pull)
+    return np.array(traj)
+
+
+def deffuant(g: nx.Graph, x0: np.ndarray, cfg: BaselineConfig, rng) -> np.ndarray:
+    """Deffuant et al. (2000): random pairwise encounters along edges.
+
+    One "step" = |E| random edge encounters, so step counts are comparable across graphs.
+    """
+    edges = np.array(g.edges())
+    x = x0.copy()
+    traj = [x.copy()]
+    for _ in range(cfg.steps):
+        for e in rng.integers(0, len(edges), len(edges)):
+            i, j = edges[e]
+            d = x[j] - x[i]
+            if abs(d) <= cfg.epsilon:
+                x[i] += cfg.mu * d
+                x[j] -= cfg.mu * d
+        traj.append(x.copy())
+    return np.array(traj)
+
+
+def friedkin_johnsen(g: nx.Graph, x0: np.ndarray, cfg: BaselineConfig, rng) -> np.ndarray:
+    """Friedkin–Johnsen (1990) as in Chitra & Musco (2020).
+
+    Innate opinions s = x0 stay fixed; expressed opinions iterate
+    z_i(t+1) = (λ s_i + Σ_j A_ij z_j(t)) / (λ + d_i).
+    """
+    a = _adjacency(g)
+    lam = cfg.stubbornness
+    denom = lam + a.sum(axis=1)
+    s = x0.copy()
+    traj = [s.copy()]
+    for _ in range(cfg.steps):
+        traj.append((lam * s + a @ traj[-1]) / denom)
+    return np.array(traj)
+
+
+MODELS: dict[str, Callable] = {
+    "degroot": degroot,
+    "bounded_confidence": bounded_confidence,
+    "deffuant": deffuant,
+    "friedkin_johnsen": friedkin_johnsen,
+}
+
+
+def run_baseline(g: nx.Graph, x0: np.ndarray, cfg: BaselineConfig, seed: int = 0) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    traj = MODELS[cfg.model](g, np.asarray(x0, dtype=float), cfg, rng)
+    return np.clip(traj, OPINION_MIN, OPINION_MAX)