{
  "schema": "leumas.docs.page/1",
  "id": "adapter:domain/keyword-cluster",
  "slug": "adapters/domain/keyword-cluster",
  "kind": "capabilities",
  "bucket": "package",
  "title": "keyword-cluster",
  "name": "Keyword Cluster",
  "eyebrow": null,
  "chip": null,
  "summary": "Keyword clustering and search-intent intelligence for SEO, PPC and content strategy. cluster groups a raw keyword list into topical clusters using a self-contained vectorizer (stemmed token overlap +...",
  "keywords": [
    "keyword-cluster",
    "topical",
    "vectorizer",
    "character-n-gram",
    "most-central",
    "keyword cluster api",
    "how to use keyword cluster",
    "intentgroup"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# keyword-cluster\n\n**AI keyword-intelligence microservice** for SEO, PPC and content strategy. Turns a raw keyword list\ninto topical clusters, search-intent groups, deduped canonicals, seed expansions and ranking-difficulty\nscores — all with a **self-contained vectorizer** (character-n-gram cosine + stemmed token overlap, the\n\"embeddings concept\" implemented offline, no ML model, no external API).\n\nEvery tool has a deterministic core that runs fully **offline**. The generative/analytical tools\n(`cluster`, `expand`) also wire an optional LLM path that enriches when a model is reachable and\nsilently falls back to the heuristic — results carry `{ mode: 'heuristic' | 'llm' }`.\n\n## Tools\n\n| Tool | Input | What it does |\n|---|---|---|\n| `cluster` | `keywords` | Groups keywords into topical clusters via fused cosine + token-overlap similarity; labels each by its most-central keyword; reports cohesion + outliers. Optional LLM cluster labels. |\n| `intentGroup` | `keywords` | Classifies each keyword into `informational` / `commercial` / `navigational` / `transactional` from signal-word lexicons; returns groups + distribution. |\n| `dedupeSimilar` | `keywords` | Collapses near-duplicate / paraphrase keywords above a similarity `threshold`, keeping one canonical per group. |\n| `expand` | `seed` | Generates variant queries around a seed: prefix/suffix modifiers, question forms, comparisons, buyer-stage, long-tail. Optional LLM variants. |\n| `difficultyEstimate` | `keyword` or `keywords` | Scores ranking difficulty 0-100 with `easy`/`medium`/`hard` bands from word count, intent, head-vs-long-tail and modifier signals; transparent factor list. |\n\n## Usage\n\n```js\nimport pack from './index.js';\n\nawait pack.adapters.cluster({\n  keywords: ['best running shoes', 'top running shoes', 'buy trail shoes', 'trail running shoes review'],\n  options: { threshold: 0.3 },\n});\n\npack.adapters.intentGroup({ keywords: ['how to tie shoes', 'buy nike shoes', 'nike login'] });\n\npack.adapters.difficultyEstimate({ keyword: 'shoes' });\n```\n\nEach tool takes ONE args object (maps 1:1 to an HTTP POST body). Invalid input throws `TypeError`.\n\n## Options\n\n`options`: `threshold` (0-1 similarity for `cluster`/`dedupeSimilar`), `ngram` (2-4 char-gram size),\n`minClusterSize`, `maxClusters`, `limit` (expand cap), `modifiers` (extra expansion suffixes),\n`narrate` (force-try the LLM label/variant path).\n\n## DRY boundaries\n\n- This OWNS **keyword-list intelligence** (clustering, intent, dedupe, expansion, difficulty).\n- It does NOT audit HTML/meta or build keyword briefs — that's the `seo` pack.\n- The tiny vectorizer is inlined and keyword-specific on purpose; it does not import the generic\n  `embeddings` pack or `a-transformation` vector tools (no cross-pack imports except `../_shared/llm.js`).\n",
  "source": {
    "path": "shared/engines/adapters/domain/keyword-cluster/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 3040,
    "hash": "ce718289b0e75228c5e64cb557eea536cae115e0"
  },
  "urls": {
    "html": "/p/adapters/domain/keyword-cluster",
    "json": "/docs/adapters/domain/keyword-cluster.json",
    "md": "/docs/adapters/domain/keyword-cluster.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}