feat: agent pipeline improvements, config externalization, and compact spawn format

.gitignore

@@ -13,3 +13,6 @@ venv/
 Wildfire_Proposal.pdf
 .idea/
 .venv/
+Research_Proposal_0317.pptx
+sumo/halifax.net.xml
+sumo/Halifax_buildings.xml

agentevac/agents/agent_state.py

@@ -47,11 +47,14 @@ class AgentRuntimeState:
             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.
         observation_history: Bounded list of system-generated local neighborhood observations.
+        institutional_history: Bounded list of institutional snapshots (forecast + annotated
+            menu) pushed each decision round.  Used by
+            ``information_model.apply_institutional_delay`` to serve stale official
+            information when ``INFO_DELAY_S > 0``.
         has_departed: True once the vehicle has been added to the SUMO simulation.
     """
 
@@ -65,6 +68,7 @@ class AgentRuntimeState:
     social_history: List[Dict[str, Any]] = field(default_factory=list)
     decision_history: List[Dict[str, Any]] = field(default_factory=list)
     observation_history: List[Dict[str, Any]] = field(default_factory=list)
+    institutional_history: List[Dict[str, Any]] = field(default_factory=list)
     has_departed: bool = True
     last_input_hash: Optional[int] = None
     last_llm_choice_idx: Optional[int] = None
@@ -237,9 +241,7 @@ def append_signal_history(
 ) -> 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``.
+    The history is bounded to ``max_items`` entries (default 16).
 
     Args:
         state: The agent whose history to update.
@@ -307,6 +309,26 @@ def append_observation_history(
     _append_bounded(state.observation_history, observation, max_items)
 
 
+def append_institutional_history(
+    state: AgentRuntimeState,
+    snapshot: Dict[str, Any],
+    *,
+    max_items: int = 16,
+) -> None:
+    """Append an institutional snapshot to the agent's institutional history.
+
+    Each snapshot contains the forecast and annotated destination/route menu
+    produced for that decision round.  Used by ``apply_institutional_delay``
+    to serve stale official information when ``INFO_DELAY_S > 0``.
+
+    Args:
+        state: The agent whose history to update.
+        snapshot: Dict with ``forecast`` and ``annotated_menu`` keys.
+        max_items: Maximum number of snapshots to retain.
+    """
+    _append_bounded(state.institutional_history, snapshot, max_items)
+
+
 def snapshot_agent_state(state: AgentRuntimeState) -> Dict[str, Any]:
     """Serialize an ``AgentRuntimeState`` to a plain dict for logging or replay.
 
@@ -331,5 +353,6 @@ def snapshot_agent_state(state: AgentRuntimeState) -> Dict[str, Any]:
         "social_history": [dict(item) for item in state.social_history],
         "decision_history": [dict(item) for item in state.decision_history],
         "observation_history": [dict(item) for item in state.observation_history],
+        "institutional_history": [dict(item) for item in state.institutional_history],
         "has_departed": bool(state.has_departed),
     }

agentevac/agents/information_model.py

@@ -1,14 +1,24 @@
-"""Information sensing and social signal processing for evacuation agents.
+"""Information sensing, institutional delay, and social signal processing for evacuation agents.
 
-This module handles the two information streams available to each agent each decision round:
+This module handles the information streams available to each agent each decision round:
 
 **Environmental signals** (``sample_environment_signal``):
     The agent observes the closest fire margin on its current edge and the minimum margin
     across the head of its planned route.  Gaussian noise (``sigma_info`` metres, std-dev)
     is injected to model imperfect sensing — e.g., smoke obscuring visibility or GPS
-    inaccuracy.  An optional delay (``INFO_DELAY_S`` seconds, converted to ``delay_rounds``)
-    is applied by replaying a stale record from the agent's signal history, simulating
-    delayed emergency broadcasts or slow rumour propagation.
+    inaccuracy.  Environmental signals are always **real-time** — personal observation
+    has no institutional delay.
+
+**Institutional delay** (``apply_institutional_delay``):
+    Official information channels (fire forecasts, route guidance, advisory labels,
+    expected-utility scores) are subject to ``INFO_DELAY_S`` seconds of institutional
+    delay.  When ``delay_rounds > 0``, the agent receives a stale snapshot from
+    ``delay_rounds`` decision periods ago.  When the agent's history is too short
+    (i.e., fewer rounds have elapsed than the delay), **no institutional information
+    is available** — the agent operates as if in a ``no_notice`` regime on that channel.
+    This models the real-world lag in emergency management information production and
+    dissemination.  In ``no_notice`` mode the institutional channel is already invisible,
+    so the delay has no additional effect.
 
 **Social signals** (``build_social_signal``):
     Peer messages from the agent's inbox are parsed with a simple keyword-vote approach.
@@ -150,6 +160,46 @@ def apply_signal_delay(
     return out
 
 
+def apply_institutional_delay(
+    history: List[Dict[str, Any]],
+    delay_rounds: int,
+) -> Optional[Dict[str, Any]]:
+    """Resolve the institutional snapshot the agent should see this round.
+
+    Institutional snapshots contain official forecast and annotated menu data
+    pushed each decision round.  When ``delay_rounds > 0``, the agent receives
+    the snapshot from ``delay_rounds`` periods ago.
+
+    Unlike ``apply_signal_delay``, this function returns ``None`` when the
+    history is too short — the agent has not yet accumulated enough rounds for
+    the first delayed report to arrive.  The caller should treat ``None`` as
+    "no institutional information available" and present a ``no_notice``-grade
+    view to the agent.
+
+    Args:
+        history: The agent's bounded ``institutional_history`` list (oldest-first).
+        delay_rounds: Number of decision periods of institutional lag.
+            When 0, returns ``None`` — caller should use the current (real-time)
+            snapshot directly.
+
+    Returns:
+        A stale institutional snapshot dict when available, or ``None`` when
+        either ``delay_rounds == 0`` (use current) or history is too short
+        (information not yet available).
+    """
+    delay = max(0, int(delay_rounds))
+    if delay <= 0:
+        # No delay — caller uses the current snapshot directly.
+        return None
+    if delay <= len(history):
+        snapshot = dict(history[-delay])
+        snapshot["is_delayed"] = True
+        snapshot["delay_rounds_applied"] = delay
+        return snapshot
+    # History too short — institutional information has not arrived yet.
+    return None
+
+
 def sample_environment_signal(
     agent_id: str,
     sim_t_s: float,