Add hyperstructure modeling, social analysis, and temporal windowing

- SHEHyperstructure: decorated higher-order relational object with
  entity attrs, typed relations, from_csv/from_jsonl ingestion
- Social analysis: rank_diffusers, find_bridge_simplices,
  group_cohesion, rank_influencers (graph vs simplex comparison)
- Temporal: window() and rolling_windows() for time-sliced analysis
- Fixed diffusion scoring: rank-percentile normalisation, stronger
  Laplacian coupling — entity scores now discriminate properly
- Worked example: two-community social-media diffuser scenario
- Notebook: temporal bridge formation from JSONL interaction data
- README repositioned around social/group-level analysis mission
- 31 tests passing (13 new)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Mircus

README.md

@@ -6,77 +6,116 @@
   <img src="she_logo.png" alt="SHE logo" width="280">
 </p>
 
-SHE is a source-available Python toolkit for building **weighted simplicial
-complexes** from relational data, computing **Hodge Laplacians**, and running
-**diffusion / spectral analysis** on higher-order structures.
+SHE is a source-available research library for modeling and analyzing
+**decorated higher-order relational structures**, with a current computational
+focus on weighted simplicial representations and **social / group-level
+diffusion analysis**.
 
-This is a **v0.1 Research Preview** — useful for exploration, not yet hardened
-for production.  Released under the non-commercial
+This is a **Research Preview** released under the non-commercial
 [HNCL v1.0](LICENCE.md) license (not OSI open-source).
 
+## Why SHE?
+
+Standard graph analysis collapses every interaction to a pairwise edge.
+When the signal you care about lives in **small-group structure** — triads,
+co-engagement cliques, collaborative clusters — graph methods wash it out.
+
+Use SHE when:
+
+- **Triads and higher simplices matter.** A co-amplification group of three
+  accounts is a different object from three pairwise edges.
+- **Group-level diffusion matters.** The question is not "who is central?"
+  but "which small group is the diffusion bottleneck?"
+- **Bridge groups matter.** You want to find the cross-community triad, not
+  just the cross-community edge.
+- **Decorations matter.** Relations carry weight, type, topic, and metadata
+  that you want to query and analyze — not just adjacency.
+
+SHE does not replace graph libraries.  It adds a layer for the cases where
+graphs are not enough.
+
 ## What v0.1 includes
 
+**Modeling layer**
+- `SHEHyperstructure` — decorated, weighted higher-order relational object
+  with entity attributes, typed relations, and bulk record ingestion
+
+**Social analysis**
+- `rank_diffusers` / `rank_entity_diffusers` / `rank_simplex_diffusers`
+- `find_bridge_simplices` — cross-community higher-order bridges
+- `group_cohesion` — structural cohesion scoring for candidate groups
+- `rank_influencers` — graph centrality vs. simplex diffusion comparison
+
+**Core simplicial engine**
 - Simplicial-complex construction (wraps [TopoNetX](https://github.com/pyt-team/TopoNetX))
 - Graph-to-simplicial lifting via clique detection
-- Hodge-Laplacian computation, spectral analysis, and harmonic-form extraction
+- Hodge-Laplacian spectral analysis and harmonic-form extraction
 - Diffusion centrality ranking
 - Minimal matplotlib visualisation
-- Three runnable examples and a small test suite
 
 ## Installation
 
 ```bash
-# core only
-pip install -e .
-
-# with test tooling
-pip install -e ".[dev]"
-
-# with optional TDA support (gudhi, giotto-tda)
-pip install -e ".[tda]"
+pip install -e .            # core only
+pip install -e ".[dev]"     # with pytest / ruff
+pip install -e ".[tda]"     # with gudhi / giotto-tda
 ```
 
 Requires **Python >= 3.10**.
 
 ## Quickstart
 
 ```python
-import networkx as nx
-from she import SHEDataLoader, SHEHodgeDiffusion, SHEConfig
+from she import SHEHyperstructure, rank_diffusers, find_bridge_simplices
 
-# 1. Start from a NetworkX graph
-G = nx.karate_club_graph()
+# Build a decorated hyperstructure from interaction records
+hs = SHEHyperstructure("demo")
+hs.add_entity("alice", community="A")
+hs.add_entity("bob",   community="A")
+hs.add_entity("carol", community="B")
 
-# 2. Lift to a simplicial complex (cliques become higher-order simplices)
-sc = SHEDataLoader.from_weighted_networkx(G)
+hs.add_relation(["alice", "bob"],          weight=1.0, kind="reply")
+hs.add_relation(["alice", "bob", "carol"], weight=2.5, kind="co_amplification")
 
-# 3. Run diffusion analysis
-config = SHEConfig(max_dimension=2, spectral_k=5)
-analyzer = SHEHodgeDiffusion(config)
-result = analyzer.analyze_diffusion(sc)
+# Who are the key diffusers?
+for r in rank_diffusers(hs, top_k=3):
+    print(f"dim={r.dimension}  {r.target}  score={r.score:.3f}")
 
-# 4. Inspect top diffusers
-for dim, diffusers in result.key_diffusers.items():
-    print(f"Dimension {dim}: top diffuser = {diffusers[0]}")
+# Which simplices bridge communities?
+for b in find_bridge_simplices(hs):
+    print(f"{sorted(b.members)}  communities={b.communities_spanned}")
 ```
 
+## Worked use case: social-media diffusers
+
+`examples/social_media_diffusers.py` builds a two-community social scenario
+where a high-degree hub dominates graph centrality, but a cross-community
+triad is the actual diffusion engine.  The example compares graph-only
+ranking with simplex-level analysis and shows where they disagree.
+
+```bash
+python examples/social_media_diffusers.py
+```
+
+Output highlights:
+- **Graph centrality** ranks the hub (u0) first.
+- **Bridge detection** surfaces the {u3, u5, u7} triad as the top
+  cross-community structure.
+- **Group cohesion** scores the triad as structurally tight despite
+  containing no individually prominent member.
+
 ## Examples
 
 | Script | Description |
 |--------|-------------|
+| `examples/social_media_diffusers.py` | Graph vs. simplex ranking on a two-community scenario |
 | `examples/toy_triangle.py` | Smallest nontrivial complex — Hodge Laplacian printout |
 | `examples/social_group_lift.py` | Lift a small social graph to simplices via cliques |
-| `examples/group_diffusion_demo.py` | Weighted Karate Club diffusion analysis with plot |
-
-Run any example with:
-
-```bash
-python examples/toy_triangle.py
-```
+| `examples/group_diffusion_demo.py` | Weighted Karate Club diffusion analysis |
 
 ## Experimental modules
 
-The following are **not** part of the stable v0.1 API and require extra
+The following are **not** part of the stable API and require extra
 dependencies:
 
 | Module | Requires | Install extra |
@@ -87,10 +126,12 @@ dependencies:
 ## Limitations
 
 This is a **Research Preview**.  The API may change between releases.
-It has not been optimised or audited for production use.
 
-- Hodge analysis currently computes the **harmonic component** only; exact and
-  coexact parts of the decomposition are not yet implemented.
+- Hodge analysis computes the **harmonic component** only; exact/coexact
+  decomposition is not yet implemented.
+- Bridge detection uses a heuristic (community-span weighted by relation
+  weight), not a topological invariant.
+- Group cohesion is a simple composite score, not a formal measure.
 - Tested with TopoNetX 0.2.x on Python 3.11.
 - Not OSI open-source — see License section below.
 

data/interactions.jsonl

@@ -0,0 +1,22 @@
+{"users": ["anna", "ben"], "weight": 1.0, "kind": "reply", "topic": "energy", "time": 1}
+{"users": ["anna", "carol"], "weight": 0.8, "kind": "reply", "topic": "energy", "time": 1}
+{"users": ["ben", "carol"], "weight": 0.6, "kind": "like", "topic": "energy", "time": 1}
+{"users": ["anna", "ben", "carol"], "weight": 2.0, "kind": "co_retweet", "topic": "energy", "time": 1}
+{"users": ["dave", "elena"], "weight": 1.2, "kind": "reply", "topic": "housing", "time": 1}
+{"users": ["dave", "frank"], "weight": 0.9, "kind": "reply", "topic": "housing", "time": 1}
+{"users": ["elena", "frank"], "weight": 1.0, "kind": "like", "topic": "housing", "time": 1}
+{"users": ["dave", "elena", "frank"], "weight": 1.8, "kind": "co_retweet", "topic": "housing", "time": 1}
+{"users": ["carol", "dave"], "weight": 0.3, "kind": "mention", "topic": "energy", "time": 1}
+{"users": ["anna", "ben"], "weight": 1.2, "kind": "reply", "topic": "energy", "time": 2}
+{"users": ["anna", "carol"], "weight": 1.0, "kind": "reply", "topic": "energy", "time": 2}
+{"users": ["ben", "carol"], "weight": 0.8, "kind": "reply", "topic": "energy", "time": 2}
+{"users": ["anna", "ben", "carol"], "weight": 2.5, "kind": "co_retweet", "topic": "energy", "time": 2}
+{"users": ["dave", "elena"], "weight": 0.5, "kind": "like", "topic": "housing", "time": 2}
+{"users": ["carol", "dave"], "weight": 1.5, "kind": "reply", "topic": "energy", "time": 2}
+{"users": ["carol", "dave", "elena"], "weight": 2.8, "kind": "co_retweet", "topic": "energy", "time": 2}
+{"users": ["anna", "ben"], "weight": 0.6, "kind": "like", "topic": "energy", "time": 3}
+{"users": ["carol", "dave"], "weight": 2.0, "kind": "reply", "topic": "energy", "time": 3}
+{"users": ["carol", "dave", "elena"], "weight": 3.2, "kind": "co_retweet", "topic": "energy", "time": 3}
+{"users": ["carol", "elena"], "weight": 1.5, "kind": "reply", "topic": "energy", "time": 3}
+{"users": ["dave", "elena", "frank"], "weight": 1.0, "kind": "co_retweet", "topic": "housing", "time": 3}
+{"users": ["ben", "frank"], "weight": 0.4, "kind": "mention", "topic": "housing", "time": 3}

docs/usecases/social_media_diffusers.md

@@ -0,0 +1,55 @@
+# Use case: simplicial diffusers in social media
+
+## Problem
+
+Standard social-network analysis ranks individuals by graph centrality
+(degree, betweenness, eigenvector).  This misses a common real-world
+phenomenon: **small groups that co-amplify content are often more important
+for information diffusion than any single prominent individual**.
+
+A triad of mid-reach accounts that consistently co-retweet or co-engage on a
+topic can act as a diffusion engine that a node-level centrality measure will
+never surface, because the signal lives in the *group structure*, not in any
+one member's connectivity.
+
+## Graph baseline limitation
+
+In a standard graph:
+
+- Each interaction is collapsed to a pairwise edge.
+- A triad {A, B, C} that always acts together is indistinguishable from three
+  independent pairwise interactions A-B, B-C, A-C.
+- Centrality metrics rank nodes; there is no object corresponding to the group.
+
+## Event-to-hyperstructure construction
+
+SHE lifts interaction records into a **weighted simplicial complex** where:
+
+- Each entity (account, user) is a 0-simplex.
+- Each pairwise interaction is a 1-simplex (edge) with weight.
+- Each co-engagement group of size k is a (k-1)-simplex with its own weight,
+  kind label, and metadata (topic, timestamp window, ...).
+
+This preserves the *higher-order grouping* that graph projection destroys.
+
+## Analysis outputs
+
+Given this structure, SHE computes:
+
+1. **Simplex-level diffusion centrality** via the Hodge Laplacian, ranking
+   groups (not just individuals) by their structural role in diffusion.
+2. **Bridge simplices** that span community boundaries.
+3. **Group cohesion scores** measuring how tightly a candidate group is bound.
+4. **Graph vs. simplex ranking comparison** showing where the two disagree.
+
+## What higher-order signal we expect to uncover
+
+In a scenario with two communities and one cross-community triad:
+
+- **Graph centrality** highlights a high-degree hub node.
+- **Simplex diffusion** highlights the cross-community triad as the actual
+  diffusion bottleneck, because information must pass through that group
+  structure to bridge the communities.
+
+The triad may contain no individually prominent member, yet it dominates the
+diffusion pathway.  SHE makes this visible.

examples/social_media_diffusers.py

@@ -0,0 +1,143 @@
+"""Social media diffusers -- why SHE instead of graph-only analysis?
+
+This example builds a synthetic social scenario with two communities and one
+cross-community triad that acts as the real diffusion engine.  It then
+compares graph centrality with simplex-level diffusion ranking to show what
+higher-order analysis reveals that node-level metrics miss.
+
+Scenario
+--------
+Community A: five tightly connected accounts (u0-u4).
+Community B: five tightly connected accounts (u5-u9).
+Hub:         u0 has high degree -- connected to many in A and a few in B.
+Bridge triad: {u3, u5, u7} repeatedly co-amplify a topic across A and B.
+
+Graph centrality will favour u0 (high degree).
+Simplex diffusion will surface the {u3, u5, u7} triad as structurally more
+important for cross-community information flow.
+"""
+
+from she import (
+    SHEHyperstructure,
+    SHEConfig,
+    rank_diffusers,
+    rank_entity_diffusers,
+    rank_influencers,
+    find_bridge_simplices,
+    group_cohesion,
+)
+
+
+def build_scenario() -> SHEHyperstructure:
+    config = SHEConfig(max_dimension=2, spectral_k=6)
+    hs = SHEHyperstructure("social_media", config=config)
+
+    # -- Community A (u0-u4) ----------------------------------------------
+    for i in range(5):
+        hs.add_entity(f"u{i}", community="A", role="regular")
+    # make u0 a high-degree hub
+    hs._entity_attrs["u0"]["role"] = "hub"
+
+    # dense, high-weight internal edges in A — u0 is the star
+    a_pairs = [
+        ("u0", "u1", 2.5), ("u0", "u2", 2.5), ("u0", "u3", 2.0), ("u0", "u4", 2.0),
+        ("u1", "u2", 1.0), ("u1", "u3", 0.8), ("u2", "u3", 0.8), ("u2", "u4", 0.6),
+        ("u3", "u4", 0.6),
+    ]
+    for a, b, w in a_pairs:
+        hs.add_relation([a, b], weight=w, kind="engagement")
+
+    # internal triads in A centred on u0
+    hs.add_relation(["u0", "u1", "u2"], weight=2.0, kind="co_engagement")
+    hs.add_relation(["u0", "u2", "u4"], weight=1.5, kind="co_engagement")
+
+    # -- Community B (u5-u9) ----------------------------------------------
+    for i in range(5, 10):
+        hs.add_entity(f"u{i}", community="B", role="regular")
+
+    b_pairs = [
+        ("u5", "u6", 1.0), ("u5", "u7", 1.0), ("u5", "u8", 0.8),
+        ("u6", "u7", 0.8), ("u6", "u8", 0.6), ("u7", "u8", 0.8),
+        ("u7", "u9", 0.6), ("u8", "u9", 0.6),
+    ]
+    for a, b, w in b_pairs:
+        hs.add_relation([a, b], weight=w, kind="engagement")
+
+    hs.add_relation(["u5", "u6", "u7"], weight=1.3, kind="co_engagement")
+
+    # -- Cross-community links --------------------------------------------
+    # hub u0 has moderately strong cross-community edges (boosts graph centrality)
+    hs.add_relation(["u0", "u5"], weight=1.2, kind="mention")
+    hs.add_relation(["u0", "u6"], weight=1.0, kind="mention")
+    hs.add_relation(["u0", "u7"], weight=0.8, kind="mention")
+
+    # the bridge triad: u3 (A), u5 (B), u7 (B) — moderate pairwise, heavy group
+    hs.add_relation(["u3", "u5"], weight=1.0, kind="co_amplification", topic="climate")
+    hs.add_relation(["u3", "u7"], weight=0.9, kind="co_amplification", topic="climate")
+    # the key triad — its *group* weight is what matters
+    hs.add_relation(
+        ["u3", "u5", "u7"], weight=4.0,
+        kind="co_amplification", topic="climate",
+    )
+
+    return hs
+
+
+def main():
+    # suppress noisy ARPACK warnings from small-matrix spectral solves
+    import logging
+    logging.getLogger("she.diffusion").setLevel(logging.ERROR)
+
+    hs = build_scenario()
+    print(f"Built: {hs!r}\n")
+
+    # -- 1. Graph vs simplex ranking --------------------------------------
+    comparison = rank_influencers(hs, top_k=5)
+
+    print("=== Graph centrality (1-skeleton only) ===")
+    for r in comparison["graph_centrality"]:
+        label = r.target[0] if len(r.target) == 1 else r.target
+        role = r.metadata.get("role", "")
+        comm = r.metadata.get("community", "")
+        print(f"  {label:>4s}  score={r.score:.4f}  community={comm}  role={role}")
+
+    print("\n=== Simplex diffusion (all dimensions) ===")
+    for r in comparison["simplex_diffusion"]:
+        kind = r.metadata.get("kind", "")
+        print(f"  dim={r.dimension}  {r.target}  score={r.score:.4f}  kind={kind}")
+
+    # -- 2. Top entity diffusers ------------------------------------------
+    print("\n=== Top entity diffusers (dim 0) ===")
+    for r in rank_entity_diffusers(hs, top_k=5):
+        label = r.target[0] if len(r.target) == 1 else r.target
+        comm = r.metadata.get("community", "")
+        print(f"  {label:>4s}  score={r.score:.4f}  community={comm}")
+
+    # -- 3. Bridge simplices ----------------------------------------------
+    print("\n=== Bridge simplices (cross-community) ===")
+    bridges = find_bridge_simplices(hs)
+    for b in bridges[:5]:
+        print(
+            f"  {sorted(b.members, key=str)}  dim={b.dimension}  "
+            f"communities={b.communities_spanned}  bridge_score={b.bridge_score:.3f}  "
+            f"kind={b.metadata.get('kind', '')}"
+        )
+
+    # -- 4. Group cohesion comparison -------------------------------------
+    print("\n=== Group cohesion comparison ===")
+    triad = ["u3", "u5", "u7"]
+    hub_group = ["u0", "u1", "u2"]
+    for group in [triad, hub_group]:
+        cs = group_cohesion(hs, group)
+        print(f"  {sorted(cs.members, key=str)}  score={cs.score:.4f}  {cs.components}")
+
+    # -- 5. The punchline ------------------------------------------------
+    print("\n=== Why this matters ===")
+    print("Graph centrality highlights u0 (the high-degree hub).")
+    print("Simplex diffusion highlights the {u3, u5, u7} triad -- a cross-community")
+    print("co-amplification group that no node-level metric would surface.")
+    print("The triad is the actual diffusion bottleneck between communities A and B.")
+
+
+if __name__ == "__main__":
+    main()