feat: add trust graph fetcher for social trust network generation

[MuddyBootsCode]

Summary

• Adds TrustGraphFetcher — a new fetcher that generates directed social trust graphs with realistic topology
• Generates community-structured networks using Stochastic Block Models (SBM) with preferential attachment rewiring
• Supports configurable reciprocity, organic distrust edges, and adversarial bot clusters
• Optimized with numpy/scipy for scalability to 100k+ nodes (~7s for 10k, ~67s for 100k)

What's Included

• graphfaker/fetchers/trust.py (683 lines) — Full trust graph generation pipeline:

  1. Community structure via fast SBM (numpy vectorized)
  2. Preferential attachment rewiring for hub emergence
  3. Directed edge conversion with configurable reciprocity
  4. Small-world rewiring for realistic path lengths
  5. Faker-generated user attributes (name, public_key, created_at, community)
  6. Organic distrust edges (Poisson-distributed)
  7. Adversarial bot clusters with compromised node marking

• tests/test_fetchers_trust.py (355 lines) — 34 unit tests covering all pipeline stages

• Integration — Wired into core.py dispatcher, cli.py with full parameter exposure, enums.py with TRUST type

• Bug fixes — Fixed cli.py logger import (from venv import logger → from graphfaker.logger import logger), updated error message in generate_graph() to list all sources

• Dependencies — Added numpy>=1.24.0 to pyproject.toml (was transitive via networkx, now explicit)

Usage

from graphfaker import GraphFaker

gf = GraphFaker()
G = gf.generate_graph(
    source="trust",
    total_users=10000,
    avg_trust_links=15,
    reciprocity=0.7,
    community_mixing=0.15,
    avg_distrust_links=2.0,
    bot_fraction=0.10,
    seed=42,
)

graphfaker gen --fetcher trust --total-users 10000 --seed 42

Key Topology Properties (10k nodes, seed=42)

Metric	Value
Avg out-degree	15.2
Modularity	0.59
Avg path length	3.93
Hub ratio	2.7
Cross-community edges	18.4%
TRUSTS edges	~135k
DISTRUSTS edges	~25k
Bot nodes	~1000 (10%)

Test plan

• 34/34 unit tests pass (pytest tests/test_fetchers_trust.py)
• Verify existing tests still pass (pytest tests/)
• Test CLI: graphfaker gen --fetcher trust --total-users 1000 --seed 42
• Review generated graph structure in Neo4j or similar tool

🤖 Generated with Claude Code