Topical Proximity Classifier: an LLM content audit tool for pruning decisions

Topical proximity classifier vs keyword clustering

Keyword clustering and proximity classification solve different problems. Clustering maps search demand before you write. Proximity classification audits what you have already published.

How does the classifier work?

The model handles the judgment and a fixed rule set assigns the tier, so you get the model's reading of each post together with repeatable buckets.

1. It learns the business from two files

config.yaml describes what the business does, where it operates and what it doesn't offer. services.csv lists each service with a short descriptor. Both go into every prompt, so each post is judged against this business's catalog, not a general idea of the topic.

2. It reads the body as well as the title

When the audit CSV has no Content column, the script fetches each URL and extracts the main text with trafilatura, up to a set character limit. A title alone gives too little to judge from: "SunPower Maxeon Panels Review" could be a 3,000-word technical breakdown or a 400-word affiliate post.

3. It classifies each post with structured output

Each post reaches the model with the business context and six worked examples that anchor the hardest boundaries, such as product review against service intent and drift against off-topic. The model reasons first, then returns five fields: reasoning, service, service_alignment, post_type and commercial_intent. The schema is enforced through strict response_format on OpenAI and a tool_use input schema on Anthropic, so the model can't answer in free text or add fields of its own.

4. Fixed rules turn the fields into a tier

The script maps post_type, service_alignment and commercial_intent to a tier with fixed rules, so identical fields always produce an identical tier. A SERVICE_INTENT post with high or medium commercial intent lands in CORE_SERVICE, and a post that supports none of the services lands in OFF_TOPIC whatever its score.

if post_type == "OFF_TOPIC" or service == "NONE":  OFF_TOPIC
if post_type == "SERVICE_INTENT" and intent in (HIGH, MEDIUM):  CORE_SERVICE
if post_type == "PRODUCT_REVIEW" and alignment >= 0.5:  CORE_PRODUCT
if post_type == "COMPARISON" and alignment >= 0.5:  ADJACENT_COMPARISON
if post_type in (EDUCATIONAL, INSTALLATION_GUIDE) and alignment >= 0.4:  ADJACENT_INFORMATIONAL
if post_type == "DESIGN_INSPIRATION":  ADJACENT_INFORMATIONAL if alignment >= 0.4 else PERIPHERAL
if post_type == "DRIFT" or alignment < 0.3:  PERIPHERAL
# anything left:  ADJACENT_INFORMATIONAL

5. A second pass rechecks the borderline calls

Every post with an alignment between 0.35 and 0.65 goes back to the model for an independent re-check, which either confirms the first call or replaces it. The overridden column records which happened. The band covers that range because single-pass calls in the middle of the scale are the ones most likely to be wrong.

How to run the Topical Proximity Classifier

You need Python 3.10 or newer and an API key from OpenAI or Anthropic. Install into a virtual environment so the tool's dependencies stay out of your system Python.

1. Install

git clone https://github.com/lumkamishi/topical-proximity.git
cd topical-proximity
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e .

2. Set your API key

export OPENAI_API_KEY="sk-..."
# or
export ANTHROPIC_API_KEY="sk-ant-..."
# Windows PowerShell: $env:OPENAI_API_KEY="sk-..."

3. Describe the business in config.yaml

Write the description the way you would brief a strategist, and state what the business doesn't sell as plainly as what it does, because exclusions drive the DRIFT and OFF_TOPIC calls. A solar installer that leaves out "we don't sell backyard solar lights" can see "Best Backyard Solar Lights" filed as a core product post.

4. List the services and the posts

services.csv holds one row per service, and audit.csv holds one row per post. URL is required, while Title, H1 and Meta Description are recommended. If a Screaming Frog crawl already gave you the body text, add it as a Content column and the fetch step is skipped.

5. Run it

topical-proximity \
  --config config.yaml \
  --services services.csv \
  --audit audit.csv \
  --output topical_proximity.csv

Model choice and cost per 500 posts

Provider and model are switched with two lines in config.yaml. These estimates from the project README include the verification pass:

Haiku suits a first pass on a large blog, while Sonnet or gpt-5.4 give better reasoning text for a client deliverable. Setting fetch_content: false and verify_alignment_range: [0, 0] roughly halves the cost, although accuracy drops with both.

What a custom topical proximity classifier costs

A custom classifier build is a fixed-scope technical project to clean up content debt and resolve cannibalization across a large URL inventory, built around your own topic map.

What a custom build delivers

• Topic map file: a structured taxonomy of your core commercial subjects, the concepts that support them, and the topics you explicitly don't cover.
• Per-URL proximity scores: every crawled URL with its alignment score, relevance band and primary entity label.
• Cannibalization report: the URLs that target the same topic and compete against each other in Google.
• Pruning roadmap: a spreadsheet listing which URLs to delete, which to redirect and which to rewrite.
• Internal link plan: source URLs, target URLs and vetted anchor text for each link.

For a home renovation client, we built a three-layer Python pipeline that combined search-value scoring, keyword cannibalization detection and GPT-based topical proximity classification, and produced a YAML topic map and a content pruning roadmap.

Every finding is prioritized by impact and effort, with high-impact cleanup listed first so your editors and engineers can start on the structural problems straight away. You also get the full pipeline code at delivery, so your team can rerun it against new pages and keep editorial work inside your strategic scope.