Feature request: no way to control the output language of LLM-generated community labels

[jerp86]

Version: 0.9.12

Problem: graphify label/cluster-only (with an LLM backend, e.g. claude-cli) names communities via label_communities() in llm.py. The prompt built in _label_batch_with_retry (llm.py, around line 2392) is a hardcoded English string with no language directive:

prompt = (
    "You are naming clusters in a knowledge graph. For each community below, "
    "return a concise 2-5 word plain-language name describing what it is about "
    "(e.g. \"Order Management\", \"Payment Flow\", \"Auth Middleware\"). "
    "Respond ONLY with a JSON object mapping the community id (as a string) to "
    "its name - no prose, no markdown fences.\n\n" + "\n".join(batch_lines)
)

There is no CLI flag or environment variable to pin the output language (checked cli.py's label/cluster-only arg parsing and llm.py for any GRAPHIFY_* env var touching labeling — none exists; the only --lang flag in the codebase is unrelated, for export callflow-html's HTML chrome language).

Impact: for non-English codebases/teams, re-running label/cluster-only across sessions produces inconsistent label language — the same community gets named in English in one relabel pass and in the team's natural language (e.g. Portuguese) in another, since the model infers language ambiently from the sampled node-label lines rather than an explicit instruction. This makes diffing/comparing labels across reclusters noisy and forces manual normalization.

Suggestion: add an explicit language instruction to the labeling prompt, controllable via a --label-language/--lang flag on label/cluster-only (or a GRAPHIFY_LABEL_LANGUAGE env var), defaulting to the current unconstrained behavior for backward compatibility.

Happy to test a patch if useful.

[jerp86]

Related gap: the hook/watch incremental path bypasses the LLM labeler entirely

Follow-up from our side. Digging into this further while investigating a separate issue (#1800), we found watch.py's incremental rebuild doesn't call label_communities() (the LLM path this issue is about) at all for any community without a saved label — it falls back to label_communities_by_hub() in cluster.py:

# watch.py
missing = {cid: members for cid, members in communities.items() if cid not in labels}
if missing:
    # Deterministic hub name (highest-degree member) beats a bare "Community N"
    # placeholder for any community without a saved label.
    from graphify.cluster import label_communities_by_hub
    labels.update(label_communities_by_hub(G, missing))

label_communities_by_hub just names the community after its highest-degree member's own label (stripping a trailing ()), with no language involved at all — it's whatever the underlying symbol/file is called. We saw this in practice: an incremental hook rebuild spun up a new community whose only members were a handful of doc nodes, and it got named xmap-language.ts (the source file of the highest-degree member) — visibly different in style, not just language, from the LLM-generated multi-word semantic names (e.g. "DSL xmap e Faixa de Problemas") sitting right next to it in the same report.

So the language-consistency problem this issue describes is really two separate gaps stacked together:

1. (this issue) no way to pin the LLM prompt's output language when it does run.
2. the hook/watch incremental path never invokes the LLM labeler at all for new/renumbered communities, so even a perfect fix for (1) wouldn't stop hook-created communities from showing up as raw hub identifiers instead of a name in any consistent language/style.

Not sure if (2) belongs in this issue or deserves its own — happy to file separately if you'd rather keep them apart. Flagging here since it's the same underlying "community naming isn't consistent across rebuild paths" user-facing symptom.

[Rishet11]

I'd love to contribute to Graphify and work on this. If there's anything specific you'd like done differently from the current discussion, let me know. I'll put together a PR.