[Bug]: use_lcc silently drops case-sensitive entity titles from every community

[zfields]

Do you need to file an issue?

• I have searched the existing issues and this bug is not already filed.
• My model is hosted on OpenAI or Azure. (N/A — reproduces independent of model provider; this is a pure data-pipeline bug, not an LLM output issue)
• I believe this is a legitimate bug, not just a question.

Describe the bug

When bringing your own graph (BYOG) with cluster_graph.use_lcc: true (the default), entities whose title contains lowercase characters are silently dropped from every community — with no warning, error, or log line. create_communities reports success and writes N communities, but coverage across all communities can be far less than the number of input entities.

Root cause: graphs/stable_lcc.py's normalize_node_name does html.unescape(name).upper().strip() before computing the largest connected component, and this uppercased form is what gets passed into hierarchical_leiden — so the cluster labels that come back out of cluster_graph() are uppercase. index/workflows/create_communities.py's create_communities() then joins those cluster labels back against entities.title via exact case-sensitive string matching (title_to_entity_id dict lookup, and relationships.merge(level_comms, left_on="source", right_on="title")). Any title that wasn't already all-uppercase fails to match: entity_map["entity_id"] comes back NaN and is dropped via .dropna(), and any community with no matched intra-community edges is dropped entirely by the final inner merge against entity_ids.

This is presumably fine for GraphRAG's own LLM-extraction pipeline, where entity names are conventionally emitted uppercase already — but it's a silent correctness bug for BYOG users bringing case-sensitive titles (e.g. a codebase's real identifier names, which is a very natural BYOG use case).

Steps to reproduce

1. Build a minimal BYOG entities.parquet / relationships.parquet per the BYOG guide with at least one entity title containing lowercase letters (e.g. FooBar, BazQux), and a relationship between two such entities.
2. Configure workflows: [create_communities, create_community_reports] with default cluster_graph.use_lcc: true.
3. Run graphrag index.
4. Inspect output/communities.parquet — the mixed-case entities never appear in any community's entity_ids, despite being connected in relationships.parquet.

Expected Behavior

Every entity that appears in a connected relationship should be assigned to some community, or the pipeline should surface a warning when input entities can't be matched back after LCC normalization.

GraphRAG Config Used

cluster_graph:
  max_cluster_size: 10
  use_lcc: true  # default - triggers the bug
workflows: [create_communities, create_community_reports, generate_text_embeddings]

Logs and screenshots

N/A — the bug produces no error output; it is a silent data-loss issue only visible by comparing entity counts in entities.parquet against total entity_ids coverage across communities.parquet.

Additional Information

• GraphRAG Version: 3.1.0
• Operating System: macOS 26.5.1
• Python Version: 3.12.13
• Related Issues: none found

[zfields]

Following up with the two fix approaches I considered, in case a maintainer has a preference before anyone puts together a PR:

Option A: Preserve original casing through stable_lcc/cluster_graph
Have _compute_leiden_communities keep a normalized→original label mapping when stable_lcc uppercases node names for the connectivity computation, and translate the cluster labels back to their original casing before returning from cluster_graph(). create_communities()'s existing case-sensitive join against entities.title would then work unmodified. This confines the uppercase normalization to an internal detail of the LCC step, with no behavior change visible downstream.

Option B: Normalize consistently on both sides of the join
Instead of translating labels back, have create_communities() apply the same normalization (html.unescape().upper().strip()) when building title_to_entity_id and when merging relationships against community labels, so both sides of every join agree. This keeps stable_lcc untouched but requires create_communities() (and any other consumer of cluster_graph()'s output) to know about and replicate that normalization independently.

My own lean is toward Option A — it fixes the root cause once, at the point where the mutation happens, rather than requiring every downstream consumer of cluster labels to independently know to re-normalize. But happy to go whichever direction you'd prefer, or a different approach entirely if there's context I'm missing about why stable_lcc normalizes case in the first place (e.g. deliberate case-insensitive entity deduplication for LLM-extracted graphs) that a fix would need to preserve.

Separately, regardless of which direction the real fix takes, it might be worth adding a coverage check/warning after create_communities (e.g. "N of M input entities were not assigned to any community") — that alone would have caught this immediately instead of requiring an entity-by-entity audit to notice the silent data loss.

Happy to put together a PR for whichever direction you'd prefer.