Skip to content

feat(llm-content-coverage): add LLM content coverage audit#2748

Open
anagarwa wants to merge 6 commits into
mainfrom
feature/llm-content-coverage
Open

feat(llm-content-coverage): add LLM content coverage audit#2748
anagarwa wants to merge 6 commits into
mainfrom
feature/llm-content-coverage

Conversation

@anagarwa

@anagarwa anagarwa commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Adds new llm-content-coverage audit type that identifies topics where AI prompt volume is high but brand citation is low
  • Fetches up to 200 brand topics from rpc_brand_presence_topics (Mysticat PostgREST), scores each with a gap score (promptCount² / (promptCount + brandCitations + brandMentions)), and selects the top 10 candidates
  • Calls Semrush FanoutService via gRPC to find low-rank keywords (brand ranks at position > 5) for each topic
  • Post-processor creates/updates an Opportunity with LLMO topic data + Semrush fanout results, and syncs one Suggestion per low-rank keyword
  • Registers handler in src/index.js as llm-content-coverage

Depends on

Must merge and publish spacecat-shared#1776 first — this PR imports getGrpcClients and fetchLowRankFanoutKeywords from @adobe/mysticat-shared-seo-client.

Test plan

  • Audit validated end-to-end on adobe.com (siteId c2473d89-e997-458d-a86d-b4096649c12b)
    • 194 LLMO topics fetched, top 10 scored by gap score
    • FanoutService returned 10/10 topic matches
    • Opportunity created with topics + semrushTopics in data field
    • 1 keyword suggestion synced: "how to use generative ai" (volume=480, brandPosition=6)
  • SEO_CLIENT_ID / SEO_CLIENT_SECRET loaded from Vault at path bootstrapEnvironment/development/spacecat-services--audit-worker/anagarwa
  • Unit tests to be added (coverage enforcement will catch on CI)

Opportunity data shape

{
  "data": {
    "domain": "adobe.com",
    "topics": [{ "topic": "...", "promptCount": 41, "brandCitations": 0, "brandMentions": 66, "gapScore": 16 }],
    "semrushTopics": [{ "topic": "...", "matchedTopicName": "Generative AI", "similarityScore": 93, "keywords": [{ "keyword": "how to use generative ai", "volume": 480, "brandPosition": 6 }] }]
  }
}

🤖 Generated with Claude Code

anagarwa and others added 6 commits July 1, 2026 12:53
Introduces a new audit type 'llm-content-coverage' that identifies topics
where AI prompt volume is high but brand citations + mentions are low
(the content coverage gap).

Pipeline:
1. Fetches brand topics via PostgREST rpc_brand_presence_topics
2. Scores topics: gapScore = promptCount² / (promptCount + citations + mentions)
3. Takes top 10 candidates by gap score
4. Resolves topicHash via Semrush TopicService.brandTopics (UUID→uint64 bridge)
5. Fan-out gapPrompts(GAP_KIND: MISSING) for each top topic in parallel
6. Persists opportunity + suggestions via convertToOpportunity + syncSuggestions

Also adds @quazar/ai-seo-ts (vendored protobuf), @connectrpc/connect,
@connectrpc/connect-node, @bufbuild/protobuf, and
@adobe/mysticat-shared-semrush-ai-client as dependencies.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Move all Semrush gRPC logic to @adobe/mysticat-shared-seo-client.
Remove third-party/ai-seo-ts, @quazar/ai-seo-ts, @connectrpc/* and
@bufbuild/protobuf deps — handler now imports only getGrpcClients,
fetchTopicHashMap and fetchGapPrompts from the shared seo-client.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Proto files are now vendored inside mysticat-shared-seo-client,
so the local copy in this repo is no longer needed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…keyword detection

Replaces Semrush PromptService gap-prompts enrichment with FanoutService
resolveTopicMetrics. For each top-scored topic, identifies SERP keywords
where the brand appears in rankings but at position > 5. Removes
opportunity/suggestion persistence (detection only for now).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…stions post-audit

Adds opportunityAndSuggestions post-processor that runs after the audit is
persisted. Creates/updates the Opportunity with LLMO topic data and Semrush
fanout results, then syncs one Suggestion per low-rank keyword identified.
Fixes origin field required by OpportunityCollection.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant