.test_clustering_debug.md

test_clustering_debug.py

Debug/diagnostic script for the cluster_modules function that exercises the module clustering pipeline against a small set of synthetic Java components and prints the raw LLM response used to produce the clustering result. It is intended for manual troubleshooting of clustering behavior rather than automated CI use, though it exits with a non-zero status on failure so it can be wired into a test runner.

Key Components

• capture_llm_response() — Monkey-patches cluster_modules.create_llm_client so the underlying LLM client's call method is wrapped, storing the raw response text in the global captured_response for later inspection.
• TestResults — Lightweight test accumulator with add_test(name, passed, details) and print_summary(), which prints a pass/fail report and returns True only if all tests passed.
• config — A Config instance built from environment variables (with sensible OpenAI/Anthropic defaults), pointing at a test repository (CODEWIKI_TEST_REPO env var or a local fixtures/sample_repo fixture).
• components — A dict of four sample Node objects (AuthController, AuthService, UserController, UserService) simulating Java classes to be clustered.
• Main flow — Calls cluster_modules(...) with the sample components, prints the captured LLM response (truncated to 2000 chars), records whether the resulting module tree is non-empty, and prints a final summary.

Usage Example

Run directly as a script; it relies on a .env.local file for API credentials:

# .env.local should define OPENAI_API_KEY / ANTHROPIC_API_KEY,
# and optionally MAIN_MODEL, CLUSTER_MODEL, FALLBACK_MODEL, CODEWIKI_TEST_REPO
python test_clustering_debug.py

Expected console output includes the model in use, the raw LLM response (useful for diagnosing malformed <GROUPED_COMPONENTS> tags), and a final TEST SUMMARY block:

🤖 Using model: gpt-4o

🔄 Clustering...

📝 LLM RESPONSE:
...

TEST SUMMARY
================================================================================
✅ PASS: clustering produces non-empty module tree
================================================================================
Total: 1, Passed: 1, Failed: 0

The script exits with code 1 if clustering fails to produce a module tree, making it suitable as a quick sanity check when debugging the clustering prompt or LLM integration.