# hashtag-strategist

Intelligent social-media hashtag strategy microservice: suggest a platform-tuned mix of reach/niche/branded hashtags for a topic (Instagram, TikTok, X/Twitter, LinkedIn, YouTube, Pinterest, Threads...


Intelligent social-media hashtag strategy microservice. Turns a topic into a platform-tuned mix of
reach / niche / branded hashtags, scores individual tags for competitiveness vs discoverability,
screens for banned/shadowban-risk tags, and enforces per-platform count limits.

Every tool has a **deterministic heuristic core that runs fully offline** (word-shape scoring, reach
tiers, curated banned list, platform tables). `suggest` additionally has an **optional LLM path** that
enriches topic→tag ideation and silently falls back to the heuristic when no model is reachable —
results are tagged `{ mode: 'heuristic' | 'llm' }`.

## Tools

| Tool | Args | Returns |
|---|---|---|
| `suggest` | `{ topic, platform?, count?, options?:{ seed, brand, mix, allowLLM } }` | hashtag set split into reach/niche/branded tiers |
| `score` | `{ hashtag }` | `{ competitiveness, reach, discoverability, tier, sizeBand, banned, advice }` |
| `bannedCheck` | `{ hashtag }` or `{ hashtags:[...] }` | per-tag safe/banned/broken/caution flags |
| `mixStrategy` | `{ topic? , hashtags?, platform?, count?, options?:{ mix, brand } }` | balanced reach/mid/niche plan + breakdown |
| `byPlatform` | `{ platform? }` | count limits, sweet-spot, default mix, formatting notes (one or all) |

Platforms: `instagram, tiktok, twitter/x, linkedin, youtube, pinterest, threads, facebook`.

## Example

```js
import pack from './index.js';
await pack.adapters.suggest({ topic: 'vegan meal prep', platform: 'instagram', count: 11 });
// → { mode, platform:'instagram', hashtags:[...], tiers:{ reach, niche, branded }, detail:[...] }

pack.adapters.score({ hashtag: '#love' });
// → { competitiveness: 96, tier:'reach', sizeBand:'mega (>5M posts…)', advice:'…' }

pack.adapters.bannedCheck({ hashtags: ['#follow4follow', '#veganmealprep', '#123'] });
// → flags follow4follow (banned) and 123 (all-numeric/broken)
```

## Heuristic model

Offline we cannot query a live post count, so competitiveness/reach is **estimated from tag shape** —
the same signals a growth marketer eyeballs: short generic single words ⇒ mega/saturated (`reach`
tier), longer multi-word/specific tags ⇒ small/`niche` tier with high discoverability. The banned list
is a curated snapshot of community-flagged / permanently-broken tags plus structural rules
(all-numeric, over-long, double underscores).

## DRY boundaries

- **Not `seo`** (keyword density, meta tags, SERP snippets) — this is social hashtag strategy.
- **Not `nlp`** (tokenization/sentiment) — reused conceptually only.
- Self-contained: the only cross-file import is `../_shared/llm.js` for the optional AI path.


---
Source: shared/engines/adapters/domain/hashtag-strategist/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/hashtag-strategist