61 lines
1.9 KiB
Markdown
61 lines
1.9 KiB
Markdown
# 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
|
|
|
|
```python
|
|
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
|
|
bash test.sh
|
|
```
|
|
|
|
## Origin
|
|
|
|
Built from empirical analysis of 6345+ real inter-agent messages in a 10-40 node swarm. [OMPU project](https://ompu.eu).
|