[Proposal] Add a CNull-gated multi-agent example + CI (10-min causality sanity check)

[mczaykowski]

Proposal

Add one self-contained example (e.g., mpe/simple_spread_v3) that demonstrates a quick causality sanity check for “emergent” behavior.

The example toggles a controller→receiver side-channel ON/OFF, sweeps a dose parameter γ, logs two scalars (C(t), B(t)), then runs CNull to produce:

• a directionality curve (ΔTE),
• null-controlled z-scores (block/circular),
• a machine-checkable verdict.json (PASS/FAIL) suitable for CI.

A companion GitHub Action runs in <10 minutes on GitHub-hosted runners and fails unless passes:true.

Motivation

Many multi-agent demos look coordinated because of shared drivers/clocks/prompts, not genuine cause→effect between agents. Users lack a small, reproducible gate to falsify “pretty synchrony” before claiming emergent communication.

This example would give PettingZoo users a practical pattern they can copy into their own projects: intervene (ON/OFF + dose), test directionality, check nulls, emit PASS/FAIL.

Pitch

What I’ll contribute (PR):

• examples/cnull_simple_spread/
• cnull_wrapper.py : CommChannelWrapper adds a 1-D side-channel to the receiver obs when cond="ON", scaled by gamma ∈ {0.0,0.2,0.4,0.6,0.8,1.0}; logs C(t) and B(t).
• run_cnull_pilot.py : runs ON/OFF × γ sweep (≤2k steps per run) and writes *_C.csv, *_B.csv.
• README.md : how to run + interpret plots/verdict.
• Analysis: either call the CNull CLI, or (if you prefer no extra dep) include a tiny analysis script that computes ΔTE, block/circular nulls, 3 plots, and verdict.json.
• CI: .github/workflows/cnull-gate.yml that runs the example and blocks merges if passes:false.

Alternatives

• No external dependency: vendor a minimal analysis script (Granger/TE diff + block/circular surrogates) so users don’t need to install anything beyond PettingZoo.
• Different env: if simple_spread_v3 isn’t ideal, we can target another Parallel-API MPE env.
• Opt-in CI: ship the workflow but run it only when a label (e.g., run-cnull) is set, to keep default CI time minimal.

Additional context

• The gate is designed as a sanity check, not a full causal discovery toolkit.
• I can maintain the example going forward and adjust to PettingZoo preferences on dependencies/CI defaults.
• Happy to share the three plots + a sample verdict.json (passes:true) from a reference run if helpful.

Checklist

• I have checked that there is no similar issue in the repo