Communities

# From graphiti_core/utils/maintenance/community_operations.py:92
def label_propagation(projection: dict[str, list[Neighbor]]) -> list[list[str]]:
    """Implement the label propagation community detection algorithm.
    
    1. Start with each node being assigned its own community
    2. Each node will take on the community of the plurality of its neighbors
    3. Ties are broken by going to the largest community
    4. Continue until no communities change during propagation
    """

Kamala Harris --[worked_with]--> Gavin Newsom
Kamala Harris --[succeeded]--> Jerry Brown
Gavin Newsom --[worked_with]--> Jerry Brown
Gavin Newsom --[appointed_by]--> Willie Brown

class CommunityNode(Node):
    uuid: str
    name: str                         # Auto-generated description
    name_embedding: list[float] | None # Vector embedding for search
    summary: str                      # Aggregate summary of members
    group_id: str
    created_at: datetime

CommunityNode(
    uuid="community-uuid-123",
    name="California State Government Leadership",
    summary="This community includes political figures who have held senior positions in California state government, including Governor, Attorney General, and Lieutenant Governor. Key members have worked together in various capacities and many have connections to San Francisco politics.",
    group_id="default",
    created_at=datetime(2024, 3, 15, tzinfo=timezone.utc)
)

class CommunityEdge(Edge):
    uuid: str
    source_node_uuid: str  # CommunityNode UUID
    target_node_uuid: str  # EntityNode UUID
    group_id: str
    created_at: datetime

from graphiti_core.utils.maintenance.community_operations import build_communities

# Build communities for all groups
community_nodes, community_edges = await build_communities(
    driver=graphiti.driver,
    llm_client=graphiti.llm_client,
    group_ids=None  # Process all groups
)

# Build communities for specific groups
community_nodes, community_edges = await build_communities(
    driver=graphiti.driver,
    llm_client=graphiti.llm_client,
    group_ids=["user_123", "user_456"]
)

print(f"Detected {len(community_nodes)} communities")

# Add episode with community updates enabled
result = await graphiti.add_episode(
    name="New Information",
    episode_body="Alice Chen joined the Platform Engineering team.",
    source=EpisodeType.text,
    reference_time=datetime.now(timezone.utc),
    update_communities=True  # Incrementally update communities
)

# Access updated communities
communities = result.communities
community_edges = result.community_edges

# For each entity, get connected entities and edge counts
projection: dict[str, list[Neighbor]] = {}

for node in nodes:
    # Find neighbors and count connections
    neighbors = await get_neighbors(node)
    projection[node.uuid] = neighbors

{
    "kamala-uuid": [
        Neighbor(node_uuid="gavin-uuid", edge_count=3),
        Neighbor(node_uuid="jerry-uuid", edge_count=2)
    ],
    "gavin-uuid": [
        Neighbor(node_uuid="kamala-uuid", edge_count=3),
        Neighbor(node_uuid="willie-uuid", edge_count=1)
    ]
}

cluster_uuids = label_propagation(projection)
# Returns: [["kamala-uuid", "gavin-uuid", "jerry-uuid"], ["willie-uuid", ...]]

await community_node.generate_name_embedding(embedder)

communities = await CommunityNode.get_by_group_ids(
    driver=graphiti.driver,
    group_ids=["default"],
    limit=50
)

for community in communities:
    print(f"{community.name}: {community.summary}")

# Query members of a specific community
records, _, _ = await graphiti.driver.execute_query("""
    MATCH (c:Community {uuid: $community_uuid})-[:HAS_MEMBER]->(e:Entity)
    RETURN e.uuid AS uuid, e.name AS name, e.summary AS summary
""", community_uuid=community.uuid)

members = [record['name'] for record in records]
print(f"Community '{community.name}' has {len(members)} members: {members}")

# Find which community an entity belongs to
records, _, _ = await graphiti.driver.execute_query("""
    MATCH (c:Community)-[:HAS_MEMBER]->(e:Entity {uuid: $entity_uuid})
    RETURN c.uuid AS uuid, c.name AS name, c.summary AS summary
""", entity_uuid=alice.uuid)

if records:
    community_name = records[0]['name']
    print(f"Alice belongs to: {community_name}")

from graphiti_core.utils.maintenance.community_operations import update_community

# Update community to include new entity
communities, edges = await update_community(
    driver=graphiti.driver,
    llm_client=graphiti.llm_client,
    embedder=graphiti.embedder,
    entity=new_entity_node
)

from graphiti_core.utils.maintenance.community_operations import remove_communities

# Remove all existing communities
await remove_communities(driver=graphiti.driver)

# Rebuild from scratch
community_nodes, community_edges = await build_communities(
    driver=graphiti.driver,
    llm_client=graphiti.llm_client,
    group_ids=None
)

# Search for communities (not individual entities)
results = await graphiti.search(
    query="California political leadership",
    # Search will match against community names and summaries
)

# Results may include CommunityNodes
for result in results:
    if isinstance(result, CommunityNode):
        print(f"Found community: {result.name}")
        print(f"Summary: {result.summary}")

# Find a relevant community
community_results = await graphiti.search("tech industry leaders")
community_uuid = community_results[0].uuid

# Get all members
members = await graphiti.driver.execute_query("""
    MATCH (c:Community {uuid: $uuid})-[:HAS_MEMBER]->(e:Entity)
    RETURN e
""", uuid=community_uuid)

communities = await CommunityNode.get_by_group_ids(
    driver=graphiti.driver,
    group_ids=["research_papers"]
)

print("Discovered research topics:")
for community in communities:
    print(f"- {community.name}")

User asks: "What do you know about California politics?"
→ Show communities: "California State Government Leadership", "San Francisco Political Figures"
→ User selects: "California State Government Leadership"
→ Show members: Kamala Harris, Gavin Newsom, Jerry Brown
→ User selects: Kamala Harris
→ Show relationships: worked with Gavin Newsom, succeeded Jerry Brown

# Find the "Engineering" community
eng_community = await CommunityNode.get_by_uuid(driver, uuid="eng-comm-uuid")

# Get all entities in that community
member_uuids = [edge.target_node_uuid 
                for edge in await CommunityEdge.get_by_uuids(
                    driver, 
                    [e.uuid for e in eng_community_edges]
                )]

# Search only within those entities' relationships
results = await graphiti.search(
    query="who is working on the platform?",
    # Filter to only edges connected to engineering community members
)

communities = await CommunityNode.get_by_group_ids(
    driver=graphiti.driver,
    group_ids=["customer_data"]
)

print(f"Your graph contains {len(communities)} main topics:")
for community in communities[:5]:  # Top 5
    print(f"\n{community.name}")
    print(f"{community.summary}")

# From community_operations.py:19
MAX_COMMUNITY_BUILD_CONCURRENCY = 10

# Limits concurrent LLM calls for summarization
semaphore = asyncio.Semaphore(MAX_COMMUNITY_BUILD_CONCURRENCY)

community_candidates: dict[int, int] = defaultdict(int)
for neighbor in neighbors:
    community_candidates[community_map[neighbor.node_uuid]] += neighbor.edge_count

community_lst.sort(reverse=True)  # Sort by count descending
candidate_rank, community_candidate = community_lst[0]

while True:
    no_change = True
    # ... propagation logic ...
    if no_change:
        break

# In a scheduled job (e.g., daily)
async def rebuild_communities_job():
    await remove_communities(driver)
    communities, edges = await build_communities(
        driver, llm_client, group_ids=None
    )
    print(f"Rebuilt {len(communities)} communities")

# Build communities per user
for user_id in user_ids:
    await build_communities(
        driver,
        llm_client,
        group_ids=[f"user_{user_id}"]
    )

communities = await CommunityNode.get_by_group_ids(driver, ["default"])

# Check for overly large communities (may need rebalancing)
large_communities = [c for c in communities if len(await get_members(c)) > 100]

# Check for singleton communities (may be noise)
singleton_communities = [c for c in communities if len(await get_members(c)) == 1]

# Use community membership as a search signal
results = await graphiti.search(
    "software engineers",
    # Boost results that belong to "Engineering" community
)

from graphiti_core.utils.maintenance.community_operations import remove_communities

await remove_communities(driver=graphiti.driver)
# Deletes all CommunityNodes and CommunityEdges
# EntityNodes and EntityEdges are preserved