Cortex - SEO LLM Insights

Cortex brings holistic, sitewide SEO analysis natively into Drupal. It correlates Google Search Console traffic, PageSpeed technical performance, and live on-page signals across your top pages, then uses an LLM to turn all of it into a prioritized, page-specific action plan, with no external SaaS required.

This is the first released component of a larger, modular site-intelligence platform. Today it ships as a focused SEO tool; the longer-term goal is a lightweight core module that does nothing on its own, with pluggable sub-modules you enable as needed, starting with this SEO analysis engine and an upcoming Analytics / KPI engine (see the Roadmap below).

Features

Cortex fetches your data, aggregates it site-wide, and synthesizes it into ranked recommendations tied to specific pages and specific numbers, rather than generic checklist advice or a raw metrics widget.

• Google Search Console integration. On a configurable schedule (cron daily/weekly, or on-demand), it pulls trailing-28-day Search Console metrics (clicks, impressions, CTR, and average position) for your top N traffic-driving URLs, and persists each run as a snapshot so you can track how your overall score moves from run to run.
• Sitewide on-page SEO audit. It fetches and parses the live HTML of each analyzed URL, not just node edit forms, so views, taxonomy pages, and the front page are covered too. It checks structured data (JSON-LD / microdata), canonical and og:url consistency, meta title/description length and duplication, image alt-text coverage, and heading hierarchy (H1 count, skipped levels). Crawling respects robots.txt and a configurable politeness delay.
• Technical performance data. PageSpeed Insights scores (performance, SEO, accessibility) for both mobile and desktop per page, plus Core Web Vitals (LCP, CLS, TBT), feeding both the dashboard gauges and the AI narrative's benchmark judgments.
• Aggregated site-level dashboard. It averages Lighthouse scores across all analyzed URLs, computes an overall site score with a run-over-run trend indicator, and surfaces a technical-health summary (missing robots.txt / sitemap.xml, counts of pages with missing structured data, title/description issues, canonical mismatches, missing alt text, or heading problems), with per-page click/impression bar charts and sortable, filterable tables.
• AI-generated insights & recommendations. The full structured dataset (Search Console + PageSpeed + on-page signals, benchmarked) is sent to an LLM via the drupal/ai module, which returns validated, structured JSON: a 3-item prioritized action plan (impact, reasoning tied to specific numbers, effort, and, where applicable, the exact affected URL) plus a full narrative report. High-impression / low-CTR pages are explicitly weighted by traffic impact, and mobile-vs-desktop discrepancies are called out separately. LLM output is validated before display: a hallucinated or injected URL in a recommendation is discarded rather than trusted.

When and why to use it. Most Drupal SEO modules are passive configuration checklists, live text checkers scoped to a single node's edit form, or raw data displays with no synthesis across them. Getting a holistic, prioritized, sitewide view today usually means exporting into an external tool or correlating the data by hand. Use Cortex when you want that synthesis (search performance, technical performance, and on-page signals reasoned over together) inside your own Drupal admin UI.

Post-Installation

1. Before you configure Drupal: set up Google API access

Cortex talks to two Google APIs (Search Console and PageSpeed Insights) using a service account. You only need to do this once.

a) Create/select a Google Cloud project and enable the APIs

• Go to the Google Cloud Console.
• Select an existing project or create a new one.
• Go to APIs & Services → Library, then find and enable both the Google Search Console API and the PageSpeed Insights API.

b) Create a service account

• Go to APIs & Services → Credentials → Create Credentials → Service Account.
• Give it a name, then click Done. (No role is required for Search Console; that permission is granted inside Search Console itself, see step d.)

c) Generate a key (JSON)

• Open the service account you just created → Keys tab → Add Key → Create new key → JSON.
• A .json file downloads. This is what Cortex uses to authenticate. Store it securely.

d) Add the service account to Search Console ⚠️ This is the step people most often miss.

• Find the service account's email address (in the JSON, or on the service account's details page, e.g. [email protected]).
• Go to Search Console → Settings → Users and permissions → Add user.
• Paste the service account email and grant it Full or Restricted permission.

2. Configure Cortex in Drupal

1. Add your keys. Go to Keys (/admin/config/system/keys) and add both credentials (the Search Console service account JSON and the PageSpeed Insights key).
2. Select the keys and test the connection. On the module's settings page (/admin/config/system/seo-llm-metrics), choose the keys you just added and run the connection test. Here you also configure your LLM provider (via the drupal/ai module), the number of top traffic-driving URLs to analyze, the refresh schedule, and the crawl politeness delay.
3. Queue an analysis. Go to the reports page (/admin/reports/seo-llm-metrics) and add an analysis to the queue.
4. Run cron and view the results on the same reports/dashboard page.

If you don't want an analysis to run on every cron run, turn that option off on the settings page.

There is no new content type to create and no text-format configuration required. Cortex operates site-wide from its own admin dashboard rather than on individual node edit forms.

Additional Requirements

Beyond Drupal core, this module requires:

• The AI (drupal/ai) module, configured with an LLM provider of your choice, for the insights and recommendations.
• A Google Cloud project with the Search Console API and PageSpeed Insights API enabled, plus a service account JSON key (see Post-Installation).
• The service account added as a user in Google Search Console for the property you want to analyze.

Your Drupal site must also be publicly reachable (or otherwise fetchable by the crawler) so the on-page audit can retrieve live HTML.

Recommended modules/libraries

Any module that improves the quality of your on-page markup will improve the signals Cortex reports on, for example Metatag (meta tags, canonical, Open Graph), Schema.org Metatag (structured data), and Simple XML Sitemap (sitemap.xml).

Similar projects

Several modules touch parts of this space, but none combine Search Console performance, PageSpeed technical data, and live on-page signals into a single AI-ranked, sitewide action plan:

• Analyze + Analyze Search Console: displays Search Console metrics entity by entity via the per-entity "Analyze" tab; no PageSpeed / on-page / GSC correlation, no site-wide averaged dashboard, and no AI-ranked action plan.
• AI Content Strategy: uses an LLM for content-gap and topic/format suggestions; focused on content strategy rather than technical SEO, with no Search Console or PageSpeed data.
• Site Audit / Audit: aggregated sitewide report on Drupal-side technical/config health (modules, config, code quality); not integrated with Search Console performance or live on-page HTML signals.
• Real-time SEO / Yoast SEO: live on-page text analysis while editing, one page at a time on the node edit form; no Search Console integration and no site-wide aggregation.
• SEO Checklist: a checkable task list of recommended SEO modules; a configuration checklist that doesn't analyze actual content, traffic, or rankings.

Roadmap

The 0.x release is a standalone SEO tool, but it is intended as the first step toward a broader, freely extensible site-intelligence platform. The planned architecture is a lightweight core module that does nothing on its own, activating capability through pluggable sub-modules. The current SEO functionality will be refactored into a SEO sub-module, joined by an Analytics / KPI sub-module.

Planned for the SEO functionality (0.x):

• Configure your own custom URL list to analyze (instead of only the top-N by traffic).
• Compare a run against a chosen earlier snapshot.
• Historical trend charts built from stored snapshots.
• More trigger options (manual/on-demand runs in addition to the queue).

Planned Analytics / KPI direction, growing in small, self-contained, incremental steps:

1. Connect the site to Matomo and/or Google Analytics and show 1–3 charts/metrics on a dashboard, refreshable manually (button), via a Drush command, and optionally on cron.
2. Send the collected data to an LLM for interpretation, and display the analysis and action items beneath the dashboard.
3. Expand the set of available charts/metrics over several iterations and make them selectable per administrator.
4. Allow baseline values and target figures to be configured.
5. Add content crawling and page categorization, with the LLM recommending which KPIs and dashboard layout fit each page type.
6. Support multiple dashboards for different audiences (executive vs. operational vs. developer).
7. Add a reporting system with daily/weekly/monthly/yearly reports (formats TBD).
8. Add alerting when selected metrics cross configurable thresholds.

Note on history: today it is a per-run snapshot list with an overall-score delta; the per-page time-series trend charts listed above are the planned next step.

Disclaimer: AI Generated Code – Mainly generated by AI, reviewed and approved by a human.