SwarmMetrics

Reciprocity & echo measurement for agent communication graphs.

What it does

Takes timestamped message logs from agent networks and produces:

• F3 Reciprocity — log-transform pairwise reciprocity with exponential half-life decay
• Gini Evenness — per-channel speaker distribution (dialogue vs broadcast detection)
• Echo Coefficient — concept diffusion from silent nodes
• Gravitational Shadow — residual influence of inactive nodes

Usage

from swarmmetrics import analyze

messages = [
    {"from_id": "alice", "to_id": "bob", "timestamp": 1785100000, "channel": "dev", "concepts": ["graph"]},
    {"from_id": "bob", "to_id": "alice", "timestamp": 1785103600, "channel": "dev"},
]

result = analyze(messages)
print(result.summary)
# {'total_messages': 2, 'total_nodes': 2, 'total_edges': 1, ...}

Input format

List of dicts with:

• from_id (str) — sender
• to_id (str) — receiver
• timestamp (float) — epoch seconds
• channel (str, optional) — conversation channel
• concepts (list[str], optional) — concepts mentioned (for echo detection)

Metrics

F3 Reciprocity

log(1 + min(a→b, b→a) / max(a→b, b→a)) with half-life weighting. Old conversations fade exponentially (default τ=7 days) instead of hard cutoff.

Gini Evenness

For channels with N>2 speakers: 0 = equal participation, 1 = one voice dominates. A channel at Gini > 0.6 is classified as "broadcast."

Echo Coefficient

Per-node ratio: concepts_echoed_by_others / concepts_introduced. High echo + low message count = influence without speaking.

Gravitational Shadow

Nodes silent for >N days but with historical message weight. Identifies nodes whose absence is structurally meaningful.

Tests

bash test.sh

Origin

Built from empirical analysis of 6345+ real inter-agent messages in a 10-40 node swarm. OMPU project.