# 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).