The precise-handle workflow — country + brand filter, bulk import, similar creators

The problem the screenshots surfaced

Real operator feedback (Mira, US 高端童车 segment): hashtag discovery returned 1000 mixed videos — brands posting their own AD inventory, small drop-shippers, plus a handful of actual creators scattered across half a dozen countries. country field was null on most rows. No way to filter "show me US real creators".

Three structural fixes shipped, plus a fourth that makes the whole flow MCP-callable.

Step-by-step walkthrough

1. 1

   Keyword cast a wide net (PR-B)

   From Claude.ai or any MCP client:

   • Call scrape_tiktok_by_keyword with keyword: "stroller review", max_videos: 200
   • Returns a job_id; the JobScheduler poll loop runs it
   • 5-15 minutes later, ~50-150 authors land in your DB

   This is the TikTok counterpart to scrape_instagram_by_hashtag / scrape_youtube_by_keyword etc — closes the gap where TikTok was the one platform with NO MCP discovery tool.

2. 2

   Filter to real US creators (PR-A)

   On /kols in the web UI:

   • Country dropdown → "US"
   • Toggle "Hide brand / store accounts" on

   Under the hood, the filter matches DBAuthor.country OR DBAuthor.country_inferred case-insensitively, and excludes is_seller_like = true. The 1000 mixed rows become 40-80 actionable US creators.

   Backfill caveat: existing authors need to be classified once after migration 015. Run POST /admin/classify-authors-pending?limit=500 until scanned drops to 0.

3. 3

   Pick a seed → expand from there (PR-D)

   Find one creator that's obviously a good fit. From Claude:

   • find_similar_creators(seed_username, limit=20)
   • Returns 20 candidates with score components per row
   • Sorted by: 10·co_mention + 3·same_category + 1·shared_hashtag

   Co-mention rules — @-mentions in the seed's last 50 videos. A creator the seed has actually collaborated with beats a random same-category match by 10x in the ranking.

4. 4

   Bulk enrich the shortlist (PR-C)

   Pick 10-15 from the similar list. Either:

   • From Claude: bulk_enrich_kols({handles: [...], max_videos_per_handle: 30})
   • From the web: paste into /kols/import

   One DBSearchJob per handle. Pre-charged in one Supabase round-trip. Each handle fires an async worker; status polled via the existing /jobs/{id} route. Optional target_list_id adds every successfully looked-up author to a KOL list.

5. 5

   Score against your brand profile

   Open any of the newly-enriched dossiers. Star ratings render automatically because your workspace brand profile is set. The Creator Overview shows the one-line recommendation; click Deep Analysis on the most promising ones for the 5-credit tier with outreach strategy + negotiation notes.
6. 6

   Generate outreach + send

   Click "Cold outreach templates" on the dossier header. The modal shows a cached draft (free) or generates one (1 credit). Email signature is filled from workspaces.email_signature — never "Your Name" / "Brand" placeholders.

From Claude — the same flow in one prompt

Because all four pieces are exposed via MCP tools, an operator can drive the whole workflow from a Claude conversation:

"Find me 20 US creators similar to @paky_test who aren't brand accounts. Enrich the top 10. Add them to my 'US skincare seeds' list."

Claude calls find_similar_creators → list_kols (with country+seller filters) → bulk_enrich_kols and reports back with the job_ids it's polling. ~4 minutes end-to-end vs the previous 30+ minutes of manual handle copy-paste.

Operator deployment checklist

1. Apply migration 015 via /admin/migrations
2. Drain the classifier backlog: POST /admin/classify-authors-pending?limit=500 until scanned=0
3. Fill in workspace brand profile so the star ratings light up
4. Set sender identity (name + brand + signature) on the same settings page so outreach drafts come back signable

What's not in this PR-bundle

• Cross-platform mention graph (seed's IG bio referencing a TikTok handle) — needs a parsed-references column on DBContact
• Audience-overlap signal (followers of seed who also follow X) — needs an Influencers Club / Modash audience-overlap API call we don't currently make
• UI for find_similar_creators on the dossier page — the data shape is ready, the button is one or two lines once the operator wants the shortcut