README.md

---
title: GuestPostSuggester
emoji: 😻
colorFrom: blue
colorTo: red
sdk: gradio
sdk_version: 6.19.0
python_version: '3.13'
app_file: app.py
pinned: false
license: mit
short_description: Find live guest-post sites, ranked by authority
---

# GuestPostSuggester

Search a catalog of ~32,000 guest-post-accepting websites for sites relevant to your topic.
Search is free and local (TF-IDF text matching, no AI call). Results are live-checked for
reachability and ranked by OpenPageRank domain authority. Click "Analyze" on any result to
crawl its blog and get ~5 AI-suggested guest-post topic ideas that fit its niche but aren't
already covered — this step calls an LLM billed to your own Hugging Face token.

## How it works

1. **Search** — enter a topic. A local TF-IDF text match (no LLM, no cost) shortlists
   relevant sites from the catalog by their title/domain/niche.
2. **Availability check** — before any site is shown, its root domain is checked for live
   reachability (httpx), so dead/parked/unreachable sites never appear in results.
3. **Ranking** — surviving sites are sorted by precomputed OpenPageRank domain authority and
   shown 10 at a time; "More" reveals the next 10 below.
4. **Analyze** (per result, needs your HF token) — crawls the site's blog for its existing
   post titles (RSS → WordPress REST API → sitemap → keyword-based blog-page discovery →
   AI-assisted HTML discovery, cheapest method first, AI only as a last resort), then an
   LLM suggests ~5 guest-post topics that fit the site but aren't already covered.

## Configuration (Space owner)

- **Secret `OPR_API_KEY`** — a free [OpenPageRank](https://www.domcop.com/openpagerank/auth/signup)
  API key. Only needed to re-run/refresh the authority-score precompute later — the Space
  ships with `data/opr_scores.json` prebuilt, so this isn't required for normal operation.
- **Persistent storage** *(optional)* — if enabled, `/data` caches domain-availability checks,
  crawled title libraries, and suggestions across restarts. Without it the app still works;
  caches just don't persist between restarts.

## Billing

The search and ranking steps are entirely free and local. The Analyze step's LLM calls run
through **Hugging Face Inference Providers using the token you enter in the UI**, so they are
billed to **you**. The token is used only for that request and is not stored.