discourse-sim 0.1.0__py3-none-any.whl

discourse_sim/__init__.py

@@ -0,0 +1,29 @@
+"""
+discourse_sim
+=============
+LLM-augmented Agent-Based Social Simulation for modelling
+public discourse dynamics following a critical real-world event.
+
+Quick start
+-----------
+from discourse_sim import DiscourseSimulation
+
+sim = DiscourseSimulation(
+    critical_event="In November 2023, Dublin city centre saw a major riot...",
+    event_date="2023-11-23",
+    n_agents=100,
+    n_days=15,
+    agent_distribution={"centrist": 0.45, "far_right": 0.20,
+                        "pro_imm": 0.25, "media": 0.10},
+    topic="immigration in Ireland",
+    ollama_model="mistral:7b-instruct-q4_0",
+)
+
+sim.run()
+df = sim.to_dataframe()
+"""
+
+from discourse_sim.core import DiscourseSimulation
+
+__all__ = ["DiscourseSimulation"]
+__version__ = "0.1.0"

discourse_sim/agents/__init__.py

@@ -0,0 +1,2 @@
+from discourse_sim.agents.agent import Agent, make_agents, QUIRK_OPTIONS
+__all__ = ["Agent", "make_agents", "QUIRK_OPTIONS"]

discourse_sim/agents/agent.py

@@ -0,0 +1,129 @@
+"""
+discourse_sim.agents.agent
+==========================
+Agent dataclass and population factory.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from discourse_sim.config import SimConfig
+
+
+QUIRK_OPTIONS = [
+    "uses sarcasm heavily",
+    "adds emojis liberally",
+    "writes short, punchy sentences",
+    "writes long reflective sentences",
+    "asks rhetorical questions constantly",
+    "uses casual slang",
+    "formal and polished tone",
+    "heavy use of hashtags",
+]
+
+
+@dataclass
+class Agent:
+    """
+    A synthetic social media user.
+
+    Identity
+    --------
+    id       : unique string identifier (e.g. "agent_0")
+    kind     : ideological type from SimConfig.agent_distribution
+    attitude : [-1, +1]  — -1 = strongly pro-topic-subject, +1 = strongly against
+    exposure : [0, 1]    — cumulative threat narrative saturation
+
+    Beliefs
+    -------
+    economic_threat_belief  : perceived economic harm from the event subject
+    cultural_threat_belief  : perceived cultural threat
+    security_threat_belief  : perceived security/crime risk (updated by threat news)
+    humanitarian_belief     : humanitarian obligation weight (updated by framing)
+
+    Psychology
+    ----------
+    openness             : [0,1] — how readily beliefs change (0=rigid, 1=open)
+    conformity           : [0,1] — peer influence susceptibility
+    emotional_reactivity : [0,1] — news impact amplifier
+    trust_peers          : [0,1] — weight given to social neighbourhood
+
+    State
+    -----
+    mood             : [-1,+1] — affective state; decays; shocked by threat news
+    messages         : list of all posts generated so far
+    attitude_history : attitude value after each timestep
+    reasoning_log    : tool-call audit trail per day
+    quirk            : writing style (assigned once, fixed)
+    """
+
+    id:       str
+    kind:     str
+    attitude: float
+    exposure: float
+
+    economic_threat_belief: float = 0.0
+    cultural_threat_belief: float = 0.0
+    security_threat_belief: float = 0.0
+    humanitarian_belief:    float = 0.0
+
+    openness:             float = 0.5
+    conformity:           float = 0.5
+    emotional_reactivity: float = 0.5
+    trust_peers:          float = 0.7
+
+    mood:             float = 0.0
+    messages:         list  = field(default_factory=list)
+    attitude_history: list  = field(default_factory=list)
+    reasoning_log:    list  = field(default_factory=list)
+    quirk:            str   = ""
+
+
+def make_agents(config: "SimConfig") -> dict[str, Agent]:
+    """
+    Spawn N agents according to SimConfig.agent_distribution and kind_priors.
+
+    The distribution is converted to a weighted sampling pool so that
+    proportions are respected even for non-round N values.
+    """
+    rng = random.Random(config.network_seed)
+
+    # Build weighted pool (oversample then trim)
+    pool: list[str] = []
+    for kind, proportion in config.agent_distribution.items():
+        count = round(proportion * config.n_agents)
+        pool.extend([kind] * count)
+
+    # Adjust pool length to exactly n_agents
+    while len(pool) < config.n_agents:
+        pool.append(rng.choice(list(config.agent_distribution.keys())))
+    pool = pool[: config.n_agents]
+    rng.shuffle(pool)
+
+    agents: dict[str, Agent] = {}
+    for i, kind in enumerate(pool):
+        priors = config.kind_priors[kind]
+
+        def u(key: str) -> float:
+            lo, hi = priors[key]
+            return rng.uniform(lo, hi)
+
+        agents[f"agent_{i}"] = Agent(
+            id=f"agent_{i}",
+            kind=kind,
+            attitude=u("attitude"),
+            exposure=rng.uniform(0.0, 0.3),
+            economic_threat_belief=u("economic_threat"),
+            cultural_threat_belief=u("cultural_threat"),
+            humanitarian_belief=u("humanitarian"),
+            openness=u("openness"),
+            emotional_reactivity=u("emotional_react"),
+            conformity=rng.uniform(0.3, 0.8),
+            trust_peers=rng.uniform(0.4, 0.9),
+        )
+
+    return agents

discourse_sim/config.py

@@ -0,0 +1,222 @@
+"""
+discourse_sim.config
+====================
+Central configuration dataclass. All user-facing parameters live here.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Dict, List, Optional
+
+
+# ── Default agent kinds and their priors ────────────────────────────────────
+# Users can extend / override these by passing custom_kind_priors to SimConfig.
+DEFAULT_KIND_PRIORS: Dict[str, dict] = {
+    "far_right": {
+        "attitude":        (0.5,   1.0),
+        "economic_threat": (0.4,   0.9),
+        "cultural_threat": (0.4,   0.9),
+        "humanitarian":    (-0.5,  0.1),
+        "openness":        (0.1,   0.4),
+        "emotional_react": (0.6,   1.0),
+    },
+    "pro_imm": {
+        "attitude":        (-1.0, -0.3),
+        "economic_threat": (-0.5,  0.1),
+        "cultural_threat": (-0.5,  0.0),
+        "humanitarian":    (0.4,   1.0),
+        "openness":        (0.6,   1.0),
+        "emotional_react": (0.3,   0.7),
+    },
+    "centrist": {
+        "attitude":        (-0.4,  0.4),
+        "economic_threat": (-0.2,  0.4),
+        "cultural_threat": (-0.2,  0.3),
+        "humanitarian":    (0.0,   0.5),
+        "openness":        (0.4,   0.7),
+        "emotional_react": (0.3,   0.6),
+    },
+    "media": {
+        "attitude":        (-0.3,  0.3),
+        "economic_threat": (-0.2,  0.3),
+        "cultural_threat": (-0.2,  0.2),
+        "humanitarian":    (0.1,   0.5),
+        "openness":        (0.5,   0.8),
+        "emotional_react": (0.2,   0.5),
+    },
+}
+
+
+@dataclass
+class SimConfig:
+    """
+    All configuration for a DiscourseSimulation run.
+
+    Required parameters
+    -------------------
+    critical_event : str
+        Plain-text description of the event all agents are reacting to.
+        This is injected into every agent prompt on every day.
+        Example:
+            "In November 2023, Dublin city centre erupted in riots following
+             a knife attack near a school. Far-right agitators set buses alight
+             and attacked Gardaí. The event dominated Irish media for weeks."
+
+    event_date : str  (ISO format: "YYYY-MM-DD")
+        Calendar date of Day 0. All subsequent days are offset from this.
+
+    topic : str
+        The subject domain agents post about.
+        Example: "immigration in Ireland", "housing policy", "climate protests"
+        Used to anchor web search queries and scoring prompts.
+
+    Optional parameters
+    -------------------
+    n_agents : int  (default 100)
+        Total number of synthetic agents.
+
+    n_days : int  (default 15)
+        Number of simulation timesteps (one per day).
+
+    agent_distribution : dict  (default Ireland 2025 empirical distribution)
+        Proportions of each agent kind. Must sum to 1.0.
+        Keys must match entries in kind_priors.
+        Example: {"centrist": 0.45, "far_right": 0.20,
+                  "pro_imm": 0.25, "media": 0.10}
+
+    kind_priors : dict  (default DEFAULT_KIND_PRIORS)
+        Per-kind prior distributions for attitude and belief dimensions.
+        Each entry: {"attitude": (lo, hi), "economic_threat": (lo, hi), ...}
+        Users can pass a fully custom dict or override individual kinds.
+
+    timeline : dict[int, str]  (default: None → auto-generated via LLM search)
+        Optional explicit daily news entries keyed by day index (0-based).
+        If provided, overrides automatic news retrieval for those days.
+        Any day not present falls back to a generic continuation message.
+        Example:
+            {
+                0: "[VERIFIED] Day 0: The march took place at ...",
+                4: "[VERIFIED] Day 4: Government announced ...",
+            }
+        If None, agents rely entirely on live DuckDuckGo search results.
+
+    search_query_prefix : str  (default: derived from topic + event summary)
+        Prefix prepended to all DuckDuckGo search queries.
+        Example: "Dublin immigration march April 2025 Ireland"
+        Override this to localise searches for non-Irish events.
+
+    ollama_model : str  (default "mistral:7b-instruct-q4_0")
+        Any Ollama model string. Model must be pulled locally.
+
+    temperature : float  (default 0.75)
+        LLM temperature for post generation.
+
+    network_k : int  (default 6)
+        Watts-Strogatz nearest-neighbour count.
+
+    network_p : float  (default 0.3)
+        Watts-Strogatz rewiring probability.
+
+    network_seed : int  (default 42)
+        Random seed for network and agent initialisation.
+
+    use_llm_scoring : bool  (default True)
+        If False, uses keyword heuristic instead of LLM for attitude scoring.
+
+    verbose : bool  (default True)
+        Print per-agent and per-day progress to stdout.
+
+    threat_keywords : list[str]
+        Words in daily news that trigger security_threat_belief increase
+        and exposure accumulation. Override for non-immigration topics.
+
+    humanitarian_keywords : list[str]
+        Words in daily news that trigger humanitarian_belief increase.
+    """
+
+    # ── Required ──────────────────────────────────────────────────────────────
+    critical_event: str
+    event_date:     str   # "YYYY-MM-DD"
+    topic:          str
+
+    # ── Agent population ──────────────────────────────────────────────────────
+    n_agents: int = 100
+    n_days:   int = 15
+
+    agent_distribution: Dict[str, float] = field(default_factory=lambda: {
+        "centrist":  0.45,
+        "far_right": 0.20,
+        "pro_imm":   0.25,
+        "media":     0.10,
+    })
+
+    kind_priors: Dict[str, dict] = field(
+        default_factory=lambda: DEFAULT_KIND_PRIORS
+    )
+
+    # ── Timeline ──────────────────────────────────────────────────────────────
+    timeline: Optional[Dict[int, str]] = None   # None = rely on live search
+
+    # ── Search ────────────────────────────────────────────────────────────────
+    search_query_prefix: Optional[str] = None   # None = auto-derived
+
+    # ── LLM ───────────────────────────────────────────────────────────────────
+    ollama_model:     str   = "mistral:7b-instruct-q4_0"
+    temperature:      float = 0.75
+    use_llm_scoring:  bool  = True
+
+    # ── Network ───────────────────────────────────────────────────────────────
+    network_k:    int   = 6
+    network_p:    float = 0.3
+    network_seed: int   = 42
+
+    # ── Belief update keywords ────────────────────────────────────────────────
+    threat_keywords: List[str] = field(default_factory=lambda: [
+        "arson", "attack", "violence", "crime", "danger",
+        "get them out", "deportation", "deport", "riot", "assault",
+    ])
+    humanitarian_keywords: List[str] = field(default_factory=lambda: [
+        "refugee", "asylum", "rights", "children", "family",
+        "compassion", "solidarity", "waiting", "humanitarian",
+    ])
+
+    # ── Display ───────────────────────────────────────────────────────────────
+    verbose: bool = True
+
+    # ── Post-init validation ──────────────────────────────────────────────────
+    def __post_init__(self):
+        # Validate date
+        try:
+            self._parsed_date = date.fromisoformat(self.event_date)
+        except ValueError:
+            raise ValueError(
+                f"event_date must be ISO format 'YYYY-MM-DD', got: {self.event_date!r}"
+            )
+
+        # Validate distribution sums to ~1.0
+        total = sum(self.agent_distribution.values())
+        if abs(total - 1.0) > 0.01:
+            raise ValueError(
+                f"agent_distribution proportions must sum to 1.0, got {total:.3f}"
+            )
+
+        # Validate all distribution keys have priors
+        for kind in self.agent_distribution:
+            if kind not in self.kind_priors:
+                raise ValueError(
+                    f"Agent kind '{kind}' in agent_distribution has no entry in kind_priors. "
+                    f"Add a prior for it or use one of: {list(self.kind_priors.keys())}"
+                )
+
+        # Auto-derive search prefix if not provided
+        if self.search_query_prefix is None:
+            # Use first 8 words of critical_event + topic
+            words = self.critical_event.split()[:8]
+            self.search_query_prefix = " ".join(words) + " " + self.topic
+
+    @property
+    def parsed_date(self) -> date:
+        return self._parsed_date