agentevac 0.1.0__py3-none-any.whl

agentevac/__init__.py

@@ -0,0 +1,13 @@
+"""AgentEvac — agent-based wildfire evacuation simulator.
+
+Couples a SUMO traffic simulation with LLM-driven agents (GPT-4o-mini) that make
+real-time evacuation decisions under different information regimes.
+
+Sub-packages:
+    agents      — per-agent decision pipeline (belief, departure, routing, etc.)
+    analysis    — calibration, experiment sweep, and metrics collection.
+    utils       — shared utilities: record/replay and fire forecast.
+    simulation  — main simulation loop and vehicle spawn configuration.
+"""
+
+__version__ = "0.1.0"

agentevac/agents/__init__.py

@@ -0,0 +1,12 @@
+"""Agent decision pipeline modules.
+
+Contains the per-agent state management and the sequential pipeline stages
+that run every ``DECISION_PERIOD_S`` seconds:
+
+    agent_state       — runtime state store and profile parameters.
+    information_model — sample noisy/delayed environment and social signals.
+    belief_model      — Bayesian hazard belief update.
+    departure_model   — three-clause departure decision logic.
+    routing_utility   — expected-utility scoring for destination/route menus.
+    scenarios         — information-regime filtering (no_notice / alert / advice).
+"""

agentevac/agents/agent_state.py

@@ -0,0 +1,236 @@
+"""Agent runtime state management for the AgentEvac wildfire evacuation simulator.
+
+This module defines the per-agent in-memory state that persists across decision rounds.
+All live agent states are stored in the global ``AGENT_STATES`` dict, which is keyed by
+vehicle ID.  The main simulation loop (``agentevac.simulation.main``) creates or retrieves state via
+``ensure_agent_state()`` before running the belief-update and departure-decision pipeline.
+
+Psychological profile parameters stored in each agent's ``profile`` dict:
+    - ``theta_trust``  : Weight given to social (neighbor) signals vs. own observations [0, 1].
+                         Higher values mean the agent trusts peer messages more.
+    - ``theta_r``      : Risk threshold; agent departs if ``p_danger > theta_r`` [0, 1].
+    - ``theta_u``      : Urgency threshold; agent departs if the urgency term falls below
+                         this value (see ``departure_model.py``) [0, 1].
+    - ``gamma``        : Discount factor controlling urgency decay over time (≈ 0.99).
+                         Each elapsed second reduces urgency by a factor of ``gamma``.
+    - ``lambda_e``     : Exposure weight in the route utility function (≥ 0).
+                         Larger values make agents more averse to hazardous routes.
+    - ``lambda_t``     : Travel-time weight in the route utility function (≥ 0).
+                         Larger values make agents prefer shorter travel times.
+"""
+
+import math
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+
+@dataclass
+class AgentRuntimeState:
+    """Holds all mutable per-agent state across decision rounds.
+
+    Attributes:
+        agent_id: Unique vehicle identifier matching the SUMO vehicle ID.
+        created_sim_t_s: Simulation time (seconds) when this agent was first registered.
+        last_sim_t_s: Simulation time of the most recent state update.
+        profile: Immutable-ish psychological parameters (theta_trust, theta_r, etc.).
+            Populated by ``ensure_agent_state`` and may be overridden by calibration sweeps.
+        belief: Current Bayesian belief distribution {p_safe, p_risky, p_danger} plus
+            derived fields (entropy, entropy_norm, uncertainty_bucket).
+        psychology: Scalar summaries derived from the belief (perceived_risk, confidence).
+        signal_history: Bounded list of recent environment signals (noisy margin observations).
+            Used by the delay model to replay stale observations.
+        social_history: Bounded list of recent social signals derived from inbox messages.
+        decision_history: Bounded list of past decision records (predeparture + routing).
+            Passed to the LLM as ``agent_self_history`` so agents can avoid repeated mistakes.
+        has_departed: True once the vehicle has been added to the SUMO simulation.
+    """
+
+    agent_id: str
+    created_sim_t_s: float
+    last_sim_t_s: float
+    profile: Dict[str, float] = field(default_factory=dict)
+    belief: Dict[str, Any] = field(default_factory=dict)
+    psychology: Dict[str, Any] = field(default_factory=dict)
+    signal_history: List[Dict[str, Any]] = field(default_factory=list)
+    social_history: List[Dict[str, Any]] = field(default_factory=list)
+    decision_history: List[Dict[str, Any]] = field(default_factory=list)
+    has_departed: bool = True
+
+
+# Global registry of all agent states, keyed by vehicle ID.
+# Populated lazily as vehicles are registered in the simulation.
+AGENT_STATES: Dict[str, AgentRuntimeState] = {}
+
+
+def ensure_agent_state(
+    agent_id: str,
+    sim_t_s: float,
+    *,
+    default_theta_trust: float = 0.5,
+    default_theta_r: float = 0.45,
+    default_theta_u: float = 0.30,
+    default_gamma: float = 0.995,
+    default_lambda_e: float = 1.0,
+    default_lambda_t: float = 0.1,
+) -> AgentRuntimeState:
+    """Retrieve an existing agent state or create a new one with default parameters.
+
+    On first call for a given ``agent_id``, initializes the belief distribution to a
+    uniform prior (maximum entropy, ``uncertainty_bucket="High"``) and sets the
+    psychology scalars to neutral values.  On subsequent calls, only updates
+    ``last_sim_t_s`` and back-fills any missing profile keys via ``setdefault``.
+
+    Args:
+        agent_id: Vehicle ID used as the state registry key.
+        sim_t_s: Current simulation time in seconds.
+        default_theta_trust: Initial social-signal trust weight (see module docstring).
+        default_theta_r: Initial risk-departure threshold.
+        default_theta_u: Initial urgency-departure threshold.
+        default_gamma: Per-second urgency discount factor.
+        default_lambda_e: Initial exposure weight for route utility scoring.
+        default_lambda_t: Initial travel-time weight for route utility scoring.
+
+    Returns:
+        The (possibly newly created) ``AgentRuntimeState`` for this vehicle.
+    """
+    state = AGENT_STATES.get(agent_id)
+    if state is None:
+        # Uniform belief = maximum entropy for a 3-state distribution.
+        uniform_entropy = math.log(3.0)
+        state = AgentRuntimeState(
+            agent_id=agent_id,
+            created_sim_t_s=float(sim_t_s),
+            last_sim_t_s=float(sim_t_s),
+            profile={
+                "theta_trust": float(default_theta_trust),
+                "theta_r": float(default_theta_r),
+                "theta_u": float(default_theta_u),
+                "gamma": float(default_gamma),
+                "lambda_e": float(default_lambda_e),
+                "lambda_t": float(default_lambda_t),
+            },
+            belief={
+                "p_safe": 1.0 / 3.0,
+                "p_risky": 1.0 / 3.0,
+                "p_danger": 1.0 / 3.0,
+                "entropy": uniform_entropy,
+                "entropy_norm": 1.0,
+                "uncertainty_bucket": "High",
+            },
+            psychology={
+                "perceived_risk": 0.5,
+                "confidence": 0.0,
+            },
+        )
+        AGENT_STATES[agent_id] = state
+    # Back-fill any profile keys added in later code versions without resetting existing ones.
+    state.profile.setdefault("theta_trust", float(default_theta_trust))
+    state.profile.setdefault("theta_r", float(default_theta_r))
+    state.profile.setdefault("theta_u", float(default_theta_u))
+    state.profile.setdefault("gamma", float(default_gamma))
+    state.profile.setdefault("lambda_e", float(default_lambda_e))
+    state.profile.setdefault("lambda_t", float(default_lambda_t))
+    state.last_sim_t_s = float(sim_t_s)
+    return state
+
+
+def _append_bounded(items: List[Dict[str, Any]], value: Dict[str, Any], max_items: int) -> None:
+    """Append ``value`` to ``items`` and trim the list to at most ``max_items`` entries.
+
+    Older entries are dropped from the front so that ``items`` always contains the most
+    recent ``max_items`` records.
+
+    Args:
+        items: The list to append to (mutated in-place).
+        value: The record to append (copied shallowly).
+        max_items: Maximum number of entries to retain.
+    """
+    items.append(dict(value))
+    if len(items) > max(1, int(max_items)):
+        del items[:-max(1, int(max_items))]
+
+
+def append_signal_history(
+    state: AgentRuntimeState,
+    signal: Dict[str, Any],
+    *,
+    max_items: int = 16,
+) -> None:
+    """Append an environment signal record to the agent's signal history.
+
+    The history is bounded to ``max_items`` entries (default 16).  The delay model in
+    ``information_model.apply_signal_delay`` uses this history to retrieve stale
+    observations when ``INFO_DELAY_S > 0``.
+
+    Args:
+        state: The agent whose history to update.
+        signal: The environment signal dict produced by ``sample_environment_signal``.
+        max_items: Maximum number of signal records to retain.
+    """
+    _append_bounded(state.signal_history, signal, max_items)
+
+
+def append_social_history(
+    state: AgentRuntimeState,
+    signal: Dict[str, Any],
+    *,
+    max_items: int = 16,
+) -> None:
+    """Append a social signal record to the agent's social history.
+
+    Social signals are derived from inbox messages by ``information_model.build_social_signal``.
+    Keeping a bounded history supports future analysis of how peer influence evolved.
+
+    Args:
+        state: The agent whose history to update.
+        signal: The social signal dict produced by ``build_social_signal``.
+        max_items: Maximum number of social signal records to retain.
+    """
+    _append_bounded(state.social_history, signal, max_items)
+
+
+def append_decision_history(
+    state: AgentRuntimeState,
+    decision: Dict[str, Any],
+    *,
+    max_items: int = 32,
+) -> None:
+    """Append a decision record to the agent's decision history.
+
+    Decision records are passed to the LLM as ``agent_self_history`` so the model can
+    avoid repeating previously ineffective choices.  The larger default cap (32) relative
+    to signal/social histories reflects the higher value of decision context.
+
+    Args:
+        state: The agent whose history to update.
+        decision: The decision record (predeparture or routing) to append.
+        max_items: Maximum number of decision records to retain.
+    """
+    _append_bounded(state.decision_history, decision, max_items)
+
+
+def snapshot_agent_state(state: AgentRuntimeState) -> Dict[str, Any]:
+    """Serialize an ``AgentRuntimeState`` to a plain dict for logging or replay.
+
+    The returned dict is JSON-serializable and contains shallow copies of all mutable
+    sub-structures.  Used by ``replay.record_agent_cognition`` to capture a point-in-time
+    snapshot of the agent's internal state.
+
+    Args:
+        state: The agent state to serialize.
+
+    Returns:
+        A JSON-serializable dict representation of the agent state.
+    """
+    return {
+        "agent_id": state.agent_id,
+        "created_sim_t_s": float(state.created_sim_t_s),
+        "last_sim_t_s": float(state.last_sim_t_s),
+        "profile": dict(state.profile),
+        "belief": dict(state.belief),
+        "psychology": dict(state.psychology),
+        "signal_history": [dict(item) for item in state.signal_history],
+        "social_history": [dict(item) for item in state.social_history],
+        "decision_history": [dict(item) for item in state.decision_history],
+        "has_departed": bool(state.has_departed),
+    }

agentevac/agents/belief_model.py

@@ -0,0 +1,289 @@
+"""Bayesian belief-update pipeline for wildfire hazard assessment.
+
+Each agent maintains a probability distribution over three hazard states:
+    - ``p_safe``   : fire is far enough that the agent's current position is safe.
+    - ``p_risky``  : fire is close enough to warrant caution but not immediate danger.
+    - ``p_danger`` : fire is imminent; departure is likely warranted.
+
+The update pipeline (exposed via ``update_agent_belief``) runs once per decision period:
+    1. Map the observed margin (meters from fire edge) to a prior triplet
+       (``categorize_hazard_state``).
+    2. If social messages are present, fuse the environment-derived prior with a
+       social-signal belief weighted by ``theta_trust`` (``fuse_env_and_social_beliefs``).
+    3. Apply temporal smoothing using a fixed inertia factor to avoid belief whiplash
+       (``smooth_belief``).
+    4. Compute Shannon entropy to quantify uncertainty (``compute_belief_entropy``).
+    5. Normalize entropy to [0, 1] and bucket it into Low / Medium / High
+       (``normalize_entropy``, ``bucket_uncertainty``).
+"""
+
+import math
+from typing import Any, Dict
+
+
+def _clamp(value: float, lo: float, hi: float) -> float:
+    """Clamp ``value`` to the closed interval [``lo``, ``hi``].
+
+    Args:
+        value: The value to clamp.
+        lo: Lower bound (inclusive).
+        hi: Upper bound (inclusive).
+
+    Returns:
+        ``value`` clipped to [``lo``, ``hi``].
+    """
+    return max(lo, min(hi, float(value)))
+
+
+def _normalize_triplet(belief: Dict[str, float]) -> Dict[str, float]:
+    """L1-normalize a {p_safe, p_risky, p_danger} belief dict to sum to 1.
+
+    If the total probability mass is zero or negative (degenerate input), returns a
+    uniform distribution so downstream code always receives a valid probability vector.
+
+    Args:
+        belief: Dict with keys "p_safe", "p_risky", "p_danger".
+
+    Returns:
+        A new dict with the same keys whose values sum to 1.0.
+    """
+    total = float(
+        belief.get("p_safe", 0.0) +
+        belief.get("p_risky", 0.0) +
+        belief.get("p_danger", 0.0)
+    )
+    if total <= 0.0:
+        return {"p_safe": 1.0 / 3.0, "p_risky": 1.0 / 3.0, "p_danger": 1.0 / 3.0}
+    return {
+        "p_safe": float(belief.get("p_safe", 0.0)) / total,
+        "p_risky": float(belief.get("p_risky", 0.0)) / total,
+        "p_danger": float(belief.get("p_danger", 0.0)) / total,
+    }
+
+
+def categorize_hazard_state(signal: Dict[str, Any]) -> Dict[str, float]:
+    """Map an observed margin (meters from fire edge) to a hazard-state prior.
+
+    Uses ``observed_margin_m`` if available, falling back to ``base_margin_m``.
+    If neither is present (e.g., no fire active), returns a uniform prior.
+
+    Threshold rationale:
+        - ≤ 0 m   : fire has reached / overtaken the edge  → near-certain danger.
+        - ≤ 100 m : fire front is on the street block       → high danger.
+        - ≤ 300 m : fire within roughly two city blocks     → risky (watch closely).
+        - ≤ 700 m : fire is a few blocks away               → elevated but manageable.
+        - > 700 m : fire is well clear of the route         → predominantly safe.
+
+    Args:
+        signal: Environment signal dict, typically from ``information_model.sample_environment_signal``.
+
+    Returns:
+        A normalized {p_safe, p_risky, p_danger} dict representing the categorical prior.
+    """
+    margin = signal.get("observed_margin_m")
+    if margin is None:
+        margin = signal.get("base_margin_m")
+    if margin is None:
+        return {"p_safe": 1.0 / 3.0, "p_risky": 1.0 / 3.0, "p_danger": 1.0 / 3.0}
+
+    margin_f = float(margin)
+    if margin_f <= 0.0:
+        return {"p_safe": 0.02, "p_risky": 0.08, "p_danger": 0.90}
+    if margin_f <= 100.0:
+        return {"p_safe": 0.05, "p_risky": 0.20, "p_danger": 0.75}
+    if margin_f <= 300.0:
+        return {"p_safe": 0.15, "p_risky": 0.55, "p_danger": 0.30}
+    if margin_f <= 700.0:
+        return {"p_safe": 0.35, "p_risky": 0.50, "p_danger": 0.15}
+    return {"p_safe": 0.75, "p_risky": 0.20, "p_danger": 0.05}
+
+
+def fuse_env_and_social_beliefs(
+    env_belief: Dict[str, float],
+    social_belief: Dict[str, float],
+    theta_trust: float,
+) -> Dict[str, float]:
+    """Fuse an environmental belief with a social-signal belief via weighted average.
+
+    The agent's trust parameter ``theta_trust`` ∈ [0, 1] determines how much weight
+    is given to peer messages relative to its own observations:
+        fused = (1 - theta_trust) * env_belief + theta_trust * social_belief
+
+    Args:
+        env_belief: Belief derived from the agent's own hazard observations.
+        social_belief: Belief inferred from neighbor inbox messages.
+        theta_trust: Weight given to social signals; 0 = ignore peers, 1 = ignore self.
+
+    Returns:
+        A normalized {p_safe, p_risky, p_danger} dict representing the fused belief.
+    """
+    social_weight = _clamp(theta_trust, 0.0, 1.0)
+    env_weight = 1.0 - social_weight
+    fused = {
+        "p_safe": env_weight * float(env_belief.get("p_safe", 0.0)) + social_weight * float(social_belief.get("p_safe", 0.0)),
+        "p_risky": env_weight * float(env_belief.get("p_risky", 0.0)) + social_weight * float(social_belief.get("p_risky", 0.0)),
+        "p_danger": env_weight * float(env_belief.get("p_danger", 0.0)) + social_weight * float(social_belief.get("p_danger", 0.0)),
+    }
+    return _normalize_triplet(fused)
+
+
+def smooth_belief(
+    prev_belief: Dict[str, float],
+    new_belief: Dict[str, float],
+    inertia: float = 0.35,
+) -> Dict[str, float]:
+    """Blend the previous belief with a newly computed belief using exponential smoothing.
+
+    Prevents erratic belief flips between decision rounds by retaining a fraction
+    (``inertia``) of the prior state:
+        smoothed = inertia * prev + (1 - inertia) * new
+
+    A higher inertia value means the agent is slower to update beliefs (more conservative).
+    The default of 0.35 balances responsiveness with stability.
+
+    Args:
+        prev_belief: The agent's belief from the previous decision round.
+        new_belief: The freshly computed belief for the current round.
+        inertia: Mixing weight for the previous belief ∈ [0, 0.999].
+
+    Returns:
+        A normalized {p_safe, p_risky, p_danger} dict representing the smoothed belief.
+    """
+    smooth = _clamp(inertia, 0.0, 0.999)
+    prev = _normalize_triplet(prev_belief)
+    new = _normalize_triplet(new_belief)
+    merged = {
+        "p_safe": smooth * prev["p_safe"] + (1.0 - smooth) * new["p_safe"],
+        "p_risky": smooth * prev["p_risky"] + (1.0 - smooth) * new["p_risky"],
+        "p_danger": smooth * prev["p_danger"] + (1.0 - smooth) * new["p_danger"],
+    }
+    return _normalize_triplet(merged)
+
+
+def compute_belief_entropy(belief: Dict[str, float]) -> float:
+    """Compute the Shannon entropy of a {p_safe, p_risky, p_danger} belief distribution.
+
+    Entropy H = -Σ p_i * log(p_i) over the three states.  The maximum possible value
+    for a 3-state uniform distribution is log(3) ≈ 1.099 nats.  A floor of 1e-12 is
+    applied to each probability to avoid log(0) singularities.
+
+    Args:
+        belief: The belief distribution dict (will be normalized internally).
+
+    Returns:
+        Shannon entropy in nats (≥ 0).
+    """
+    norm = _normalize_triplet(belief)
+    total = 0.0
+    for key in ("p_safe", "p_risky", "p_danger"):
+        p = max(1e-12, float(norm[key]))
+        total -= p * math.log(p)
+    return total
+
+
+def normalize_entropy(entropy: float) -> float:
+    """Normalize Shannon entropy to the range [0, 1] relative to the 3-state maximum.
+
+    Divides raw entropy by log(3) so that a uniform distribution maps to 1.0 and a
+    fully confident belief maps to 0.0.
+
+    Args:
+        entropy: Raw Shannon entropy in nats.
+
+    Returns:
+        Normalized entropy ∈ [0, 1].
+    """
+    max_entropy = math.log(3.0)
+    if max_entropy <= 0.0:
+        return 0.0
+    return _clamp(float(entropy) / max_entropy, 0.0, 1.0)
+
+
+def bucket_uncertainty(entropy_norm: float) -> str:
+    """Discretize normalized entropy into a human-readable uncertainty label.
+
+    Thresholds:
+        - "Low"    : entropy_norm ≤ 0.33  (agent is fairly confident)
+        - "Medium" : entropy_norm ≤ 0.67  (moderate uncertainty)
+        - "High"   : entropy_norm >  0.67  (agent is highly uncertain)
+
+    The label is included in the LLM prompt so the model can reason about its own
+    epistemic state without having to interpret raw entropy values.
+
+    Args:
+        entropy_norm: Normalized entropy ∈ [0, 1].
+
+    Returns:
+        One of "Low", "Medium", or "High".
+    """
+    val = _clamp(entropy_norm, 0.0, 1.0)
+    if val <= 0.33:
+        return "Low"
+    if val <= 0.67:
+        return "Medium"
+    return "High"
+
+
+def update_agent_belief(
+    prev_belief: Dict[str, float],
+    env_signal: Dict[str, Any],
+    social_signal: Dict[str, Any],
+    theta_trust: float,
+    inertia: float = 0.35,
+) -> Dict[str, Any]:
+    """Run the full Bayesian belief-update pipeline for one decision round.
+
+    Steps:
+        1. Convert environment signal margin to a categorical prior (``categorize_hazard_state``).
+        2. If peer messages exist, fuse env prior with social belief via ``theta_trust``
+           (``fuse_env_and_social_beliefs``); otherwise use env prior directly.
+        3. Apply temporal smoothing against the previous belief (``smooth_belief``).
+        4. Compute and normalize Shannon entropy; bucket into Low / Medium / High.
+
+    Args:
+        prev_belief: The agent's belief dict from the previous decision round.
+        env_signal: Environment signal produced by ``information_model.sample_environment_signal``.
+        social_signal: Social signal produced by ``information_model.build_social_signal``.
+        theta_trust: Social-signal trust weight ∈ [0, 1] (from agent profile).
+        inertia: Temporal smoothing factor ∈ [0, 0.999].
+
+    Returns:
+        An enriched belief dict containing:
+            - p_safe, p_risky, p_danger    : smoothed posterior probabilities
+            - entropy, entropy_norm        : Shannon entropy (raw and normalized)
+            - uncertainty_bucket           : "Low", "Medium", or "High"
+            - env_weight, social_weight    : fusion weights applied this round
+            - env_belief, social_belief    : component beliefs before fusion
+    """
+    env_belief = categorize_hazard_state(env_signal)
+
+    social_count = int(social_signal.get("message_count", 0) or 0)
+    social_belief_raw = social_signal.get("social_belief") or {}
+    if social_count > 0:
+        social_belief = _normalize_triplet(social_belief_raw)
+        fused = fuse_env_and_social_beliefs(env_belief, social_belief, theta_trust)
+        social_weight = _clamp(theta_trust, 0.0, 1.0)
+        env_weight = 1.0 - social_weight
+    else:
+        # No messages in inbox: rely entirely on own environmental observation.
+        social_belief = {"p_safe": 1.0 / 3.0, "p_risky": 1.0 / 3.0, "p_danger": 1.0 / 3.0}
+        fused = dict(env_belief)
+        social_weight = 0.0
+        env_weight = 1.0
+
+    smoothed = smooth_belief(prev_belief or env_belief, fused, inertia=inertia)
+    entropy = compute_belief_entropy(smoothed)
+    entropy_norm = normalize_entropy(entropy)
+
+    return {
+        "p_safe": smoothed["p_safe"],
+        "p_risky": smoothed["p_risky"],
+        "p_danger": smoothed["p_danger"],
+        "entropy": round(entropy, 4),
+        "entropy_norm": round(entropy_norm, 4),
+        "uncertainty_bucket": bucket_uncertainty(entropy_norm),
+        "env_weight": round(env_weight, 4),
+        "social_weight": round(social_weight, 4),
+        "env_belief": env_belief,
+        "social_belief": social_belief,
+    }

agentevac/agents/departure_model.py

@@ -0,0 +1,82 @@
+"""Departure decision rule for pre-evacuation agents.
+
+An agent waits at its spawn edge until this module's ``should_depart_now`` function
+returns ``True``.  The function implements a three-clause OR rule:
+
+    1. **Risk threshold** (``risk_threshold``):
+       The agent's estimated danger probability exceeds its personal threshold
+       ``theta_r``.  This is the primary, reactive trigger.
+
+    2. **Urgency decay** (``urgency_threshold``):
+       The urgency term ``gamma^elapsed_s * p_safe`` falls below ``theta_u``.
+       As time passes, the discount factor ``gamma`` (< 1) erodes the "stay safe"
+       signal so that an agent that has been waiting a long time will eventually
+       feel compelled to act — even if ``p_danger`` is still low.  This captures
+       the real-world observation that people eventually evacuate out of a growing
+       general unease rather than a discrete danger trigger.
+
+    3. **Low-confidence precaution** (``low_confidence_precaution``):
+       If the agent is highly uncertain (``confidence < 0.15``) *and* the danger
+       probability has reached at least 60 % of ``theta_r``, it departs
+       pre-emptively.  This prevents agents from staying frozen in high-entropy
+       situations where they should arguably err on the side of caution.
+"""
+
+from typing import Any, Dict, Tuple
+
+from agentevac.agents.agent_state import AgentRuntimeState
+
+
+def should_depart_now(
+    agent_state: AgentRuntimeState,
+    belief: Dict[str, Any],
+    psychology: Dict[str, Any],
+    sim_t_s: float,
+) -> Tuple[bool, str]:
+    """Evaluate whether an agent should depart from its spawn edge at the current tick.
+
+    Applies three departure clauses in priority order (first match wins):
+        1. ``risk_threshold``        : ``p_danger > theta_r``
+        2. ``urgency_threshold``     : ``gamma^elapsed_s * p_safe < theta_u``
+        3. ``low_confidence_precaution``: ``confidence < 0.15`` and
+                                         ``p_danger >= max(0.20, theta_r * 0.6)``
+
+    If none of the clauses fire, returns ``(False, "wait")``.
+
+    Args:
+        agent_state: The agent's runtime state (supplies profile parameters and creation time).
+        belief: Current Bayesian belief dict with keys "p_danger", "p_safe", etc.
+        psychology: Current psychology dict with key "confidence".
+        sim_t_s: Current simulation time in seconds.
+
+    Returns:
+        A ``(should_depart, reason)`` tuple where ``reason`` is one of
+        "risk_threshold", "urgency_threshold", "low_confidence_precaution", or "wait".
+    """
+    p_danger = float(belief.get("p_danger", 0.0))
+    p_safe = float(belief.get("p_safe", 0.0))
+    theta_r = float(agent_state.profile.get("theta_r", 0.45))
+    theta_u = float(agent_state.profile.get("theta_u", 0.30))
+    gamma = float(agent_state.profile.get("gamma", 0.995))
+    created_t = float(agent_state.created_sim_t_s)
+    elapsed_s = max(0.0, float(sim_t_s) - created_t)
+
+    # Clause 1: Direct danger threshold.
+    if p_danger > theta_r:
+        return True, "risk_threshold"
+
+    # Clause 2: Urgency decay — the longer the agent waits, the lower gamma^t * p_safe
+    # becomes, eventually dropping below theta_u.  This forces eventual action even in
+    # low-information environments.
+    urgency_term = (gamma ** elapsed_s) * p_safe
+    if urgency_term < theta_u:
+        return True, "urgency_threshold"
+
+    # Clause 3: High uncertainty + non-trivial danger probability → err on the side of
+    # caution.  Only fires when the agent is genuinely uncertain (low confidence) and
+    # danger is already elevated relative to its own risk threshold.
+    confidence = float(psychology.get("confidence", 0.0))
+    if confidence < 0.15 and p_danger >= max(0.20, theta_r * 0.6):
+        return True, "low_confidence_precaution"
+
+    return False, "wait"