Update

Author: arianXdev

.github/workflows/ci.yml

@@ -29,9 +29,9 @@ jobs:
 
       - name: Smoke-test CLI
         run: |
-          constitution-sim validate --constitution examples/simple_constitution.yaml
-          constitution-sim validate --constitution examples/advanced_constitution.yaml
-          constitution-sim validate --constitution examples/strong_executive_constitution.yaml
+          constitution-sim validate --constitution constitutions/simple_constitution.yaml
+          constitution-sim validate --constitution constitutions/advanced_constitution.yaml
+          constitution-sim validate --constitution constitutions/strong_executive_constitution.yaml
 
       - name: Run pytest
         run: pytest -q

README.md

@@ -33,15 +33,11 @@ so the project also runs offline / in CI / with zero API keys.
   Judiciary, Media, Bureaucracy) gets its own LLM system prompt. The
   Executive is ambitious; the Judiciary is reactive; the Media chases a
   narrative; the Bureaucracy implements steadily.
-- **Agent memory.** Each agent sees its own recent decisions (turn,
-  action, legal or not) so it can reason about continuity.
-- **Schema-driven constitutions.** Strict Pydantic v2 models; YAML in,
-  typed objects out. Errors are explicit and structured.
-- **Rules engine is source of truth.** Agents propose typed actions;
-  the engine accepts or rejects with a reason. The LLM cannot mutate
-  state directly.
-- **Partial observability.** Each role gets a state view filtered by
-  its `observation_limits`.
+- **Agent memory & shared history.** Each agent remembers its own recent decisions and can see a public history of what other actors just did (if the constitution allows).
+- **Inter-agent deliberation.** Each turn features a deliberation phase where agents can negotiate, threaten, or signal intent by sending messages to each other's inboxes.
+- **Schema-driven constitutions.** Strict Pydantic v2 models; YAML in, typed objects out. Constitutions can enforce communication limits (e.g. authoritarian gag orders).
+- **Rules engine is source of truth.** Agents propose typed actions; the engine accepts or rejects with a reason. The LLM cannot mutate state directly.
+- **Partial observability.** Each role gets a state view filtered by its `observation_limits`.
 - **Institutional metrics.** Power concentration, deadlock, trust
   volatility, legitimacy, corruption pressure, emergency-power drift.
 - **Repeated-run evaluation harness.** Multi-seed runs with pandas /
@@ -90,8 +86,8 @@ This exposes a `constitution-sim` console entry point.
 ```bash
 export OPENAI_API_KEY=sk-...
 constitution-sim run \
-  --constitution examples/advanced_constitution.yaml \
-  --scenario     examples/scenario.yaml \
+  --constitution constitutions/advanced_constitution.yaml \
+  --scenario     constitutions/scenario.yaml \
   --turns 20 --seed 42 \
   --log         /tmp/cs/events.jsonl \
   --metrics-out /tmp/cs/metrics.csv
@@ -119,12 +115,12 @@ constitution-sim run --agent-type heuristic ...
 
 ```bash
 # 1. Validate a constitution YAML against the schema.
-constitution-sim validate --constitution examples/advanced_constitution.yaml
+constitution-sim validate --constitution constitutions/advanced_constitution.yaml
 
 # 2. Run a simulation (single seed or multi-seed evaluation).
 constitution-sim run \
-  --constitution examples/advanced_constitution.yaml \
-  --scenario     examples/scenario.yaml \
+  --constitution constitutions/advanced_constitution.yaml \
+  --scenario     constitutions/scenario.yaml \
   --turns 30 --runs 5 --seed 42 \
   --log         /tmp/cs/events.jsonl \
   --metrics-out /tmp/cs/metrics.csv \
@@ -145,8 +141,9 @@ For each turn, the LLM agent is prompted with:
 - The constitution's name, description, and the list of other roles.
 - Its own declared goals and utility weights (from the YAML).
 - A partial state view filtered by its `observation_limits`.
-- A short memory of its own recent decisions (and whether they were
-  legal).
+- **Public political history**: recent public actions taken by all actors.
+- **Inbox messages**: any negotiation/signals received during the turn's deliberation phase.
+- A short memory of its own recent decisions (and whether they were legal).
 - The exact set of typed actions it's allowed to return.
 
 It replies with one JSON object describing a single action. If the LLM
@@ -164,7 +161,7 @@ src/constitution_sim/
   scenarios/     Shock model + ScenarioEngine
   analysis/      MetricsCollector, Evaluator, plot
   app/           CLI (validate / run / replay / compare)
-examples/
+constitutions/
   simple_constitution.yaml
   advanced_constitution.yaml
   strong_executive_constitution.yaml
@@ -219,7 +216,5 @@ like I'm 10" walkthrough.
 This is an MVP, not a finished research instrument. The following are
 explicit non-goals at this stage:
 
-- Multi-actor coalition formation / strategic communication.
-- Persistent economic/demographic simulation (state variables are
-  scalars, not vector economies).
+- Persistent economic/demographic simulation (state variables are scalars, not vector economies).
 - Fine-tuned LLMs or RL self-play.

examples/advanced_constitution.yaml constitutions/advanced_constitution.yamlexamples/advanced_constitution.yaml renamed to constitutions/advanced_constitution.yaml

@@ -1,5 +1,5 @@
 # Five-branch constitution exercising every role in the system. Use this
-# (paired with examples/scenario.yaml) to see the full simulation surface.
+# (paired with constitutions/scenario.yaml) to see the full simulation surface.
 name: "Advanced Constitution"
 version: "2.0"
 description: "Executive + Legislature + Judiciary + Media + Bureaucracy."

constitutions/authoritarian_constitution.yaml

@@ -0,0 +1,95 @@
+name: "Authoritarian Junta"
+version: "1.0"
+description: >
+  A highly restrictive constitution where power is concentrated in the Executive,
+  communication is heavily restricted, and other roles have limited visibility
+  and influence.
+
+initial_state:
+  variables:
+    public_trust: 0.3
+    budget: 2000.0
+    state_capacity: 0.8
+    authoritarian_control: 0.9
+
+allow_emergency_powers: true
+
+roles:
+  Executive:
+    name: "Executive"
+    permissions:
+      - "ProposeLaw"
+      - "DeclareEmergency"
+      - "LiftEmergency"
+      - "ImplementPolicy"
+      - "AppointJudge"
+      - "DoNothing"
+    goals:
+      - "Maintain absolute order and stability."
+      - "Consolidate power and marginalize opposition."
+    utility_weights:
+      authoritarian_control: 1.5
+      state_capacity: 1.0
+      public_trust: 0.2
+    observation_limits:
+      see_variables: true
+      see_active_laws: true
+      see_pending_bills: true
+      see_active_shocks: true
+      see_others_actions: true
+      can_send_messages: true
+      allowed_message_recipients: [] # Can talk to anyone
+
+  Judiciary:
+    name: "Judiciary"
+    permissions:
+      - "StrikeDownLaw"
+      - "DoNothing"
+    goals:
+      - "Survive the regime."
+    utility_weights:
+      authoritarian_control: -0.5
+      public_trust: 0.5
+    observation_limits:
+      see_variables: true
+      see_active_laws: true
+      see_pending_bills: false
+      see_active_shocks: true
+      see_others_actions: false # Blind to political history
+      can_send_messages: false  # Gag order on judges
+      allowed_message_recipients: []
+
+  Media:
+    name: "Media"
+    permissions:
+      - "PublishStory"
+      - "DoNothing"
+    goals:
+      - "Publish state-approved narratives."
+    utility_weights:
+      authoritarian_control: 1.0
+    observation_limits:
+      see_variables: true
+      variable_allowlist: ["public_trust", "state_capacity"] # Cannot see authoritarian_control
+      see_active_laws: true
+      see_pending_bills: false
+      see_active_shocks: false
+      see_others_actions: false
+      can_send_messages: true
+      allowed_message_recipients: ["Executive"] # Can only talk to Executive censors
+
+rules:
+  - name: "Executive Supremacy"
+    description: "The Executive has broad powers and cannot be easily checked."
+    allowed_actions: ["ProposeLaw", "DeclareEmergency", "LiftEmergency", "ImplementPolicy", "AppointJudge"]
+    applies_to_roles: ["Executive"]
+
+  - name: "Judicial Review (Restricted)"
+    description: "Judges can strike down laws, but are effectively gagged from communicating."
+    allowed_actions: ["StrikeDownLaw"]
+    applies_to_roles: ["Judiciary"]
+
+  - name: "State Media"
+    description: "The Media is an arm of the state."
+    allowed_actions: ["PublishStory"]
+    applies_to_roles: ["Media"]

examples/scenario.yaml constitutions/scenario.yamlexamples/scenario.yaml renamed to constitutions/scenario.yaml

@@ -43,8 +43,10 @@ src/constitution_sim/
     state.py           WorldState (canonical) and StateView (per-role projection)
     actions.py         Typed action classes
     events.py          EventRecord (one row per logged decision)
+    messages.py        Message and DealProposal models for inter-agent communication
   core/
     engine.py          SimulationEngine + EventLogger
+    message_bus.py     MessageBus (handles message routing and filters)
     rules.py           RulesEngine (legality decisions + reasons)
     scheduler.py       Round-robin scheduler
   agents/
@@ -76,31 +78,32 @@ src/constitution_sim/
                    \              /
                     \            /
                   SimulationEngine ----> EventLogger (.jsonl)
-                    /     |     \
-                   /      |      \
-            Scheduler  Agents  MetricsCollector
-                          |          \
-                       StateView      DataFrame ----> plots + compare
+                  /   |    |    \
+                 /    |    |     \
+         Scheduler Messages Agents MetricsCollector
+                           |          \
+                        StateView      DataFrame ----> plots + compare
 ```
 
 Per turn:
 
-1. `Scheduler.get_next_actor()` returns an `actor_id`.
-2. `SimulationEngine.get_state_view(role_name)` builds a partial view
-   that respects the role's `ObservationLimits`.
-3. The agent's `decide(state_view)` returns a typed `Action`.
-4. `RulesEngine.is_legal(role, action, state)` returns
+1. **Deliberation Phase**: All agents generate messages (`communicate()`) which are routed via the `MessageBus`.
+2. `Scheduler.get_next_actor()` returns an `actor_id`.
+3. `SimulationEngine.get_state_view(role_name)` builds a partial view
+   that respects the role's `ObservationLimits`, including the public political history.
+4. The agent's `decide_with_messages(state_view, inbox)` returns a typed `Action`.
+5. `RulesEngine.is_legal(role, action, state)` returns
    `(bool, reason)`. The reason is always stored.
-5. `EventLogger.log(EventRecord)` records the attempt — legal or not.
-6. If legal, `SimulationEngine.apply_action(actor_id, action, state)`
-   mutates the `WorldState`.
-7. The engine calls `agent.remember(turn, action_type, is_legal)` so
+6. `EventLogger.log(EventRecord)` records the attempt — legal or not.
+7. If legal, `SimulationEngine.apply_action(actor_id, action, state)`
+   mutates the `WorldState` and records the public action in `state.recent_actions`.
+8. The engine calls `agent.remember(turn, action_type, is_legal)` so
    agents that maintain memory (LLM) can see their own history next
    turn.
-8. `ScenarioEngine.tick(state)` ages active shocks and triggers new
+9. `ScenarioEngine.tick(state)` ages active shocks and triggers new
    ones.
-9. `MetricsCollector.collect(state)` snapshots metrics.
-10. Turn counter increments.
+10. `MetricsCollector.collect(state)` snapshots metrics.
+11. Turn counter increments.
 
 ## Agent cognition
 
@@ -115,6 +118,8 @@ a prompt that includes:
 - The **constitution context**: name, description, list of other roles.
 - The agent's declared **goals** and **utility weights** from the YAML.
 - A **filtered state view** (per-role observation limits applied).
+- **Public political history**: recently executed actions by all actors (if permitted).
+- **Inbox**: messages sent by other actors during the current turn's deliberation phase.
 - A **rolling memory** of the agent's own recent decisions and whether
   they were legal.
 - The **exact set of typed actions** the role is allowed to return.
@@ -144,7 +149,7 @@ All randomness flows through a single seeded `random.Random` per agent
 
 `Role.observation_limits` (`ObservationLimits`) controls what fields of
 the `WorldState` flow into the agent's `StateView`. Examples in
-`examples/advanced_constitution.yaml`:
+`constitutions/advanced_constitution.yaml`:
 
 - Bureaucracy: `see_pending_bills: false` — bureaucrats don't see
   drafts.
@@ -167,6 +172,8 @@ The `MetricsCollector` snapshots per turn:
 | corruption_proxy    | total illegal-action attempts                               |
 | emergency_active    | 1 if a state of emergency is currently active               |
 | emergency_turns     | cumulative turns spent under emergency powers               |
+| communication_volume| number of messages sent over the message bus                |
+| active_coalitions   | number of formally declared coalitions                      |
 
 Plus the raw `state.variables` and counts of laws / bills / shocks.
 

examples/simple_constitution.yaml constitutions/simple_constitution.yamlexamples/simple_constitution.yaml renamed to constitutions/simple_constitution.yaml

@@ -54,7 +54,7 @@ works in both modes.
 
 ```bash
 constitution-sim run \
-  --constitution examples/simple_constitution.yaml \
+  --constitution constitutions/simple_constitution.yaml \
   --turns 6 \
   --log /tmp/my_first_run.jsonl
 ```
@@ -95,8 +95,8 @@ First events:
 
 ```bash
 constitution-sim run \
-  --constitution examples/advanced_constitution.yaml \
-  --scenario     examples/scenario.yaml \
+  --constitution constitutions/advanced_constitution.yaml \
+  --scenario     constitutions/scenario.yaml \
   --turns 30 --runs 5 --seed 42 \
   --log         /tmp/cs/events.jsonl \
   --metrics-out /tmp/cs/metrics.csv \
@@ -112,14 +112,14 @@ shocks firing in the middle, and `.png` plots written to
 
 ```bash
 # Run A: balanced (advanced)
-constitution-sim run --constitution examples/advanced_constitution.yaml \
-  --scenario examples/scenario.yaml --turns 12 --runs 3 --seed 11 \
+constitution-sim run --constitution constitutions/advanced_constitution.yaml \
+  --scenario constitutions/scenario.yaml --turns 12 --runs 3 --seed 11 \
   --log /tmp/A/events.jsonl --metrics-out /tmp/A/metrics.csv \
   --plot-dir /tmp/A/plots
 
 # Run B: power-grab (strong executive)
-constitution-sim run --constitution examples/strong_executive_constitution.yaml \
-  --scenario examples/scenario.yaml --turns 12 --runs 3 --seed 11 \
+constitution-sim run --constitution constitutions/strong_executive_constitution.yaml \
+  --scenario constitutions/scenario.yaml --turns 12 --runs 3 --seed 11 \
   --log /tmp/B/events.jsonl --metrics-out /tmp/B/metrics.csv \
   --plot-dir /tmp/B/plots
 
@@ -146,7 +146,7 @@ back. That's the framework working.
 
 ## 8. Editing a constitution
 
-Open `examples/simple_constitution.yaml`. The structure:
+Open `constitutions/simple_constitution.yaml`. The structure:
 
 ```yaml
 name: "My Constitution"
@@ -203,12 +203,12 @@ Knobs you can turn:
 After editing, validate:
 
 ```bash
-constitution-sim validate --constitution examples/my_constitution.yaml
+constitution-sim validate --constitution constitutions/my_constitution.yaml
 ```
 
 ## 9. Editing a scenario
 
-`examples/scenario.yaml` lists *shocks* — sudden events that nudge the
+`constitutions/scenario.yaml` lists *shocks* — sudden events that nudge the
 world's variables:
 
 ```yaml
@@ -266,7 +266,7 @@ columns:
 
 ## 12. Five experiments to try this weekend
 
-1. **The dictator test.** Use `examples/strong_executive_constitution.yaml`.
+1. **The dictator test.** Use `constitutions/strong_executive_constitution.yaml`.
    Watch `power_concentration` climb above 0.9. Then in the YAML, add
    `StrikeDownLaw` back to the Judiciary's `permissions` — re-run and
    watch it drop.
@@ -307,12 +307,12 @@ exactly why the rules engine rejected it.
 
 ```bash
 # Validate
-constitution-sim validate --constitution examples/advanced_constitution.yaml
+constitution-sim validate --constitution constitutions/advanced_constitution.yaml
 
 # One quick AI-powered simulation (auto-picks LLM if a key is set)
 constitution-sim run \
-  --constitution examples/advanced_constitution.yaml \
-  --scenario     examples/scenario.yaml \
+  --constitution constitutions/advanced_constitution.yaml \
+  --scenario     constitutions/scenario.yaml \
   --turns 10 --log /tmp/quick.jsonl
 
 # Force the heuristic agent (deterministic, no API needed)

…mples/strong_executive_constitution.yaml …tions/strong_executive_constitution.yamlexamples/strong_executive_constitution.yaml renamed to constitutions/strong_executive_constitution.yaml examples/strong_executive_constitution.yaml renamed to constitutions/strong_executive_constitution.yaml

@@ -2,11 +2,25 @@
 from constitution_sim.models.state import StateView
 from constitution_sim.models.actions import Action
 
+from typing import List
+from constitution_sim.models.messages import Message
+
 class BaseAgent(ABC):
     def __init__(self, agent_id: str, role_name: str):
         self.agent_id = agent_id
         self.role_name = role_name
 
+    def communicate(self, state_view: StateView, inbox: List[Message]) -> List[Message]:
+        """Optional deliberation phase: return messages to send to others."""
+        return []
+
+    def decide_with_messages(self, state_view: StateView, inbox: List[Message]) -> Action:
+        """Decide on the next action, optionally using received messages.
+        
+        Default implementation ignores messages and calls decide().
+        """
+        return self.decide(state_view)
+        
     @abstractmethod
     def decide(self, state_view: StateView) -> Action:
         """Decide on the next action based on the partial state view."""