social_graph_ranking v1.0.0

name: social_graph_ranking description: Ranks who matters in a social graph: degree, betweenness, harmonic closeness, eigenvector, and PageRank centrality plus Louvain community detection over any edge list, via a tested CLI. Use when an agent needs to identify influencers, find brokers and bridge accounts, map communities, or pick seed spreaders in a network built from open data.

Social Graph Ranking

Purpose

Turn an edge list into an answer to "who actually matters here." Computes five centrality measures, VoteRank seed spreaders, and Louvain communities, then cross-checks the measures against each other so the agent reports robust findings instead of one number. Built for networks an agent can legally obtain: Bluesky follow graphs, public datasets, mention/reply graphs, collaboration networks. See references/data-sources.md for what is actually collectible and what is not.

Workflow

1. Build the edge list. One row per relationship. CSV with a source,target[,weight] header, or SNAP-style plain src dst [weight] lines. For follower data, record source as the FOLLOWER and target as the account being followed. Anonymize handles before sharing the report.
2. Run the CLI.

bash
   pip install networkx
   python3 bin/sg_rank.py edges.csv --directed --top 15 --out report.json
   

Flags: --format plain for SNAP-style files; --top N for ranking depth; --resolution for Louvain granularity (>1 finds smaller communities); --seed for reproducibility.

1. Read the consensus first. The report's consensus_top lists nodes that rank in the top-N of two or more measures. A node that leads on every measure is a safe call. A node that leads on only one measure is a specialist; see references/measure-guide.md for what each specialty means.
2. Map communities. communities count, modularity, and community_sizes tell you whether the network has real subgroups. Modularity around 0.3 or higher means strong structure; near zero means one blob.
3. Report with caveats. State the data window, the boundary (who was included), and which measures agreed. Never present a centrality rank as "the most influential person," only as "top-ranked in this graph."

Output Contract

--out report.json produces:

• nodes, edges, directed, connected: graph basics
• rankings: per-measure top-N lists of {node, score} for degree (or in_degree/out_degree when directed), betweenness, harmonic_closeness, pagerank, eigenvector (undirected, when defined)
• voterank_spreaders: top-10 seed nodes for maximum spread
• communities, modularity, community_sizes: Louvain partition summary
• consensus_top: nodes in the top-N of 2+ measures, with which measures
• betweenness_sampled: true when exact betweenness was too expensive

Operating Rules

1. No single measure is "importance." Degree counts friends, betweenness finds brokers, PageRank finds the followed, eigenvector finds the connected-to-power. Report the measure that matches the question being asked.
2. Edge direction decides everything. Follower -> followee is the convention this skill assumes. If the input has it backwards, fix the input, not the interpretation.
3. Betweenness is exact under 2,000 nodes and sampled (k=256) above that. On graphs over ~100k nodes, skip betweenness and lean on PageRank + degree.
4. Louvain has a resolution limit: tiny real communities can merge into big ones. If small groups matter, raise --resolution and compare.
5. The graph is a sample, not the world. Deleted accounts, private profiles, bots, and follow-back rings all distort the rankings. Say so in the report.
6. Work from public data only. Do not scrape behind logins, do not publish ranked lists of real people's handles without a clear public-interest reason, and keep raw edge lists private.