AI-powered SEO keyword discovery, topic clustering, competitor analysis, and content gap identification — grounded in real search data, zero hallucinations.

Architecture

ProjectContext + SeoConfig
        │
        ▼
┌──────────────────────────────────────────┐
│            SEO Engine Orchestrator       │
│                                          │
│  1. Seed Query Expansion                 │
│     (company + industry + seedKeywords)  │
│                                          │
│  2. Data Collection (parallel)           │
│     ├── Serper Search Agent              │
│     │   (related searches, PAA,          │
│     │    organic snippets, volume proxy) │
│     ├── Serper Autocomplete Agent        │
│     │   (long-tail suggestions)          │
│     └── Serper Competitor Agent          │
│         (top-10 SERP positions)          │
│                                          │
│  3. LLM Evaluation (Gemini/Claude)       │
│     → Strict context filtering           │
│     → Topic Clustering + Intent Mapping  │
│                                          │
│  4. Content Gap Analysis (LLM)           │
│     → Compare clusters vs existing pages │
│     → Identify missing content           │
└──────────────────────────────────────────┘
        │
        ▼
   SeoEngineOutput
   (clusters, gaps, competitors, discarded)

Quick Start

import { runSeoEngine } from "@mintel/seo-engine";

const result = await runSeoEngine(
  {
    companyName: "KLZ Cables",
    industry: "Mittelspannungskabel, Kabeltiefbau",
    briefing: "B2B provider of specialized medium-voltage cables.",
    targetAudience: "Bauleiter, Netzbetreiber",
    competitors: ["nkt.de", "faberkabel.de"],
    seedKeywords: ["NA2XS2Y", "VPE-isoliert"],
    existingPages: [
      { url: "/produkte", title: "Produkte" },
      { url: "/kontakt", title: "Kontakt" },
    ],
    locale: { gl: "de", hl: "de" },
  },
  {
    serperApiKey: process.env.SERPER_API_KEY!,
    openRouterApiKey: process.env.OPENROUTER_API_KEY!,
  },
);

Configuration

`ProjectContext`

Field	Type	Description
`companyName`	`string?`	Client company name
`industry`	`string?`	Industry / main focus keywords
`briefing`	`string?`	Project briefing text
`targetAudience`	`string?`	Who the content targets
`competitors`	`string[]?`	Competitor domains to analyze
`seedKeywords`	`string[]?`	Explicit seed keywords beyond auto-derived
`existingPages`	`{ url, title }[]?`	Current site pages for content gap analysis
`customGuidelines`	`string?`	Extra strict filtering rules for the LLM
`locale`	`{ gl: string, hl: string }?`	Google locale (default: `de`)

`SeoConfig`

Field	Type	Description
`serperApiKey`	`string`	Required. Serper API key
`openRouterApiKey`	`string`	Required. OpenRouter API key
`model`	`string?`	LLM model (default: `google/gemini-2.5-pro`)
`maxKeywords`	`number?`	Cap total keywords returned

Output

interface SeoEngineOutput {
  topicClusters: TopicCluster[]; // Grouped keywords with intent + scores
  competitorRankings: CompetitorRanking[]; // Who ranks for your terms
  contentGaps: ContentGap[]; // Missing pages you should create
  discardedTerms: string[]; // Terms filtered out (with reasons)
}

Agents

Agent	Source	Data
`serper-agent`	Serper `/search`	Related searches, PAA, snippets
`serper-autocomplete`	Serper `/autocomplete`	Google Autocomplete long-tail terms
`serper-competitors`	Serper `/search`	Competitor SERP positions

API Keys

Serper — serper.dev (pay-per-search, ~$0.001/query)
OpenRouter — openrouter.ai (pay-per-token)

No monthly subscriptions. Pure pay-on-demand.

Development

pnpm install          # from monorepo root
pnpm --filter @mintel/seo-engine build
npx tsx src/test-run.ts   # smoke test (needs API keys in .env)