Semantic Keyword Clustering

Features

• SentenceTransformer embeddings (default all-MiniLM-L6-v2, any SBERT model via --model-name)
• PolyFuzz clustering with configurable similarity threshold (default 0.80)
• Spoke (cluster name) taken from the highest volume keyword with --volume, otherwise the shortest keyword
• Hub roll-up from the most common word in each spoke
• Interactive sunburst or treemap HTML chart
• CPU or CUDA GPU support; native Excel pivot output on Windows only

How to use

1. 1 Prepare your keyword list in CSV format
2. 2 Run the CLI tool with your file path (keyword column auto-detected, or set --column-name)
3. 3 Adjust the similarity threshold if needed (default 0.80)
4. 4 Review clusters: spoke is the cluster name, hub is a broader one-word roll-up
5. 5 Explore the interactive HTML visualisation
6. 6 Collect the auto-saved output CSV and Excel workbook

Frequently asked questions

What does my CSV need to look like?

The CLI auto-detects the keyword column if it is named Keyword, Keywords, Search Term or Search Terms (any casing of those); otherwise pass --column-name. File encoding is auto-detected with chardet, and UTF-16 files (typical of some tool exports) are read as whitespace-delimited. Bad lines are skipped rather than failing the run.

What is the difference between hub and spoke in the output?

The spoke is the cluster name: the highest volume keyword in the cluster if you pass --volume, otherwise the shortest keyword. The hub is a broader roll-up, taken as the most common single word within the spoke name (number-only words excluded), which gives you a two-level hierarchy for pivoting.

How should the volume column be formatted?

As plain integers if possible. The tool strips every non-digit character before converting, so '1,200' becomes 1200, but '1.2k' becomes 12 and any range like '100-1k' is mangled. Clean abbreviated volumes before running.

Can I speed it up or use a different model?

Yes. Pass --device cuda to run embeddings on an NVIDIA GPU, and --model-name to use any SentenceTransformer model from sbert.net instead of the default all-MiniLM-L6-v2. Larger models cluster more accurately but embed more slowly.

Why does --excel-pivot do nothing on my Mac?

The native Excel pivot table is built by automating Excel through win32com, so it only works on Windows with Excel installed. On other platforms (or if automation fails) you still get a two-sheet workbook: a pandas-indexed PivotTable sheet plus the flat Clustered Keywords sheet.

Why are some keywords labelled no_cluster?

Any keyword whose similarity to every other keyword falls below the threshold (default 0.80), or that ends up alone in a cluster of one, is assigned to no_cluster rather than forced into a poor fit. Lower --min-similarity to cluster more aggressively.