 Kpa-clawbot
|
e66085092e
|
feat: neighbor affinity API endpoints (#482) — milestone 2 (#508)
## Summary
Milestone 2 of the neighbor affinity graph (#482). Adds two API
endpoints that expose the neighbor graph built in M1 (PR #507).
### Endpoints
#### `GET /api/nodes/{pubkey}/neighbors`
Returns neighbors for a specific node with affinity scores.
**Query params:** `min_count` (default 1), `min_score` (default 0.0),
`include_ambiguous` (default true)
**Response shape:**
```json
{
"node": "pubkey",
"neighbors": [
{ "pubkey": "...", "prefix": "BB", "name": "...", "role": "repeater",
"count": 847, "score": 0.95, "first_seen": "...", "last_seen": "...",
"avg_snr": -8.2, "observers": ["obs1"], "ambiguous": false }
],
"total_observations": 847
}
```
Ambiguous entries have `candidates` array; unresolved prefixes have
`unresolved: true`.
#### `GET /api/analytics/neighbor-graph`
Returns full graph summary for analytics/visualization.
**Query params:** `min_count` (default 5), `min_score` (default 0.1),
`region` (IATA code filter)
**Response shape:**
```json
{
"nodes": [{ "pubkey": "...", "name": "...", "role": "...", "neighbor_count": 5 }],
"edges": [{ "source": "...", "target": "...", "weight": 847, "score": 0.95, "ambiguous": false }],
"stats": { "total_nodes": 42, "total_edges": 87, "ambiguous_edges": 3, "avg_cluster_size": 4.2 }
}
```
### Wiring
- `NeighborGraph` + `neighborMu` added to `Server` struct
- Lazy initialization: graph built on first API call, cached with 60s
TTL
- Node name/role lookups via existing `getCachedNodesAndPM()`
- Region filtering via existing `resolveRegionObservers()`
### Tests (15 tests)
- Empty graph, single neighbor, multiple neighbors (sorted by score)
- Ambiguous candidates with candidate list
- Unresolved prefix (orphan) with `unresolved: true`
- `min_count` filter, `min_score` filter, `include_ambiguous=false`
filter
- Unknown node returns 200 with empty neighbors
- Graph endpoint: empty, with edges, default min_count, ambiguous count
- Region filter (graceful when no store)
- Response shape validation (all required keys present)
All existing tests continue to pass.
Part of #482
---------
Co-authored-by: you <you@example.com>
|
2026-04-02 21:30:23 -07:00 |
|