Community labels remain default (Community 0, Community 1, etc.) even when Gemini semantic extraction succeeds

[wuhao1044530652]

Hi, thank you for building Graphify.

I found an issue (or possibly a missing feature / documentation gap) related to community naming.

Summary

Even when semantic extraction with Gemini succeeds, the generated community labels still remain default values like:

• Community 0
• Community 1
• Community 2

This makes the community navigation/report much less useful, because the clusters are not given meaningful semantic names.

Environment

• Graphify package: graphifyy
• Tested versions:
  • 0.8.13
  • 0.8.26
• OS: Windows
• Python: running inside a dedicated virtual environment
• LLM backend: Gemini
• API key provided via GOOGLE_API_KEY

What I tested

I upgraded from 0.8.13 to 0.8.26 and tested again in a clean output directory.

Command used for extraction:

python -m graphify extract . --backend gemini --out graphify-gemini-upgrade-test --api-timeout 120 --max-concurrency 2

The extraction succeeded and Gemini was clearly used. Example output included token usage like:

• semantic extraction completed
• tokens consumed
• graph.json and .graphify_analysis.json were generated

Then I ran:

python -m graphify cluster-only graphify-gemini-upgrade-test

After that, Graphify generated:

• .graphify_labels.json
• GRAPH_REPORT.md

Actual behavior

The generated .graphify_labels.json contains only default labels such as:

{
  "0": "Community 0",
  "1": "Community 1",
  "2": "Community 2"
}

And GRAPH_REPORT.md shows community navigation entries like:

• Community 0
• Community 1
• Community 2

In my test, all generated community labels were still default Community N values.

Expected behavior

One of the following would be helpful:

1. Preferred: when an LLM backend is available and semantic extraction succeeds, Graphify should generate meaningful community names automatically, such as:

   • "Order Management"
   • "Payment Flow"
   • "User Admin"
   • etc.

2. Alternative: if semantic community naming is not currently supported, the docs should clearly state that:

   • clustering is semantic/structural,
   • but community labels are only fallback placeholders unless another step is performed.

Why this matters

The graph nodes themselves are extracted correctly, and the clustering appears to work.
The problem is specifically that the community display labels are not semantic, so the report looks unfinished or misleading.

For example, the actual graph contains meaningful nodes/classes/methods, but the report UI only shows generic community names.

Additional notes

I also noticed that after extract, Graphify generates:

• graph.json
• .graphify_analysis.json
• manifest.json

but does not generate:

• .graphify_labels.json
• GRAPH_REPORT.md

until cluster-only is run.

If this is intended, that is fine, but it may be worth documenting more explicitly.

Question

Is semantic community naming supposed to happen automatically in the current pipeline?

If yes, this may be a bug.
If no, would you consider adding an optional step to auto-label communities using the configured LLM backend?

Thanks again.

[safishamsi]

Thanks for the detailed report @wuhao1044530652 - you diagnosed it precisely. Implemented in c8b329d, shipping in the next release.

What was happening (answer to your question)

Community naming was an agent step, not a backend step - and that's the key distinction. When you run /graphify inside an orchestrating agent (Claude Code, Gemini CLI), the agent reads .graphify_analysis.json and names the communities itself with its own reasoning (skill.md Step 5 - no API call). That's why it "worked with Claude": you were running inside Claude Code, and Claude did the labeling.

When you run the bare CLI (python -m graphify extract . --backend gemini), there is no agent to do Step 5 - the --backend only powers semantic node/edge extraction. So communities stayed Community N. This was true for every backend, including --backend claude; it wasn't a Gemini-specific bug. So: not a bug, a missing feature for standalone use - exactly your "Alternative (2)" framing, and you also asked for "Preferred (1)", so I built that.

The fix

Standalone runs now auto-name communities using the configured backend in one batched call:

• graphify cluster-only <path> (your exact repro) now names communities automatically when no .graphify_labels.json exists yet, writes real names, and regenerates the report. Your two-command flow now produces meaningful labels with no extra step.
• graphify label <path> - new subcommand to (re)generate names on demand.
• --no-label opts out (keep Community N); --backend=<name> overrides auto-detection.
• It degrades gracefully: no backend configured / API error / malformed reply -> falls back to Community N with a clear message, never crashes.

So your run becomes:

python -m graphify extract . --backend gemini --out graphify-gemini-upgrade-test
python -m graphify cluster-only graphify-gemini-upgrade-test
# communities now named: "Order Management", "Payment Flow", ...

On your secondary observation

You're right that extract produces graph.json + .graphify_analysis.json but not GRAPH_REPORT.md / .graphify_labels.json until cluster-only runs. That's intended - extract is the expensive LLM pass; clustering + labeling + report is the cheap deterministic post-step you re-run with different resolutions. extract now prints a hint pointing you at cluster-only so it's explicit.

Tested with the backend mocked (no network): happy path, partial/fenced/malformed replies, and the no-backend fallback. Full suite green.