An audit engine and an autonomous agent that make a site legible to AI, not just to search engines.

01 Why AEO/GEO, not just SEO

This project is not a traditional SEO tool. Traditional SEO optimizes for search engine crawlers ranking a page in a list of blue links. This tool optimizes for a broader and newer audience: the answer engines and generative models that read a page once, extract a claim from it, and present that claim directly to a user — often without a click-through.

02 The two‑part system

These are two separate codebases that hand off a single CSV file between them.

The two parts are independently runnable — you can audit a site without ever touching its repo, and you can run the fix agents against any CSV in the right shape, not only one this audit engine produced. The CSV handoff contract defines that shape exactly.

03 Discovery & fetchingPART 1

04 What gets measuredPART 1

Every number the scoring layer uses is either directly observed by the browser or computed from what it observed — nothing is estimated or fabricated when a real measurement isn't available.

• Core Web Vitals: LCP and CLS are captured via PerformanceObserver injected before page scripts run — these are genuinely measurable in a headless browser. INP is always reported as not_measured, since it requires a real user interaction a headless crawl never produces.
• JS-dependency ratio: raw (non-JS) word count divided by rendered word count — a low ratio means the page's content is mostly injected by JavaScript, a real risk for crawlers that don't execute it.
• Status codes & redirects: taken from the actual navigation response chain Playwright observes, cross-checked against a plain HTTP fetch.
• Timing: TTFB and load time come from the browser's own Navigation Timing API, not a synthetic stopwatch.

05 Scoring: SEO ScorePART 1

A weighted composite across three categories, each built from individually-verifiable checks with a real measured_value attached, not just a pass/fail label.

Content-length thresholds are page-type-aware — a homepage, an article, and a standard page are held to different word-count bars rather than one universal number.

06 Scoring: AI Readiness ScorePART 1

A deliberately separate scoring system from the SEO score. It estimates how prepared a page is to be understood, summarized, and cited by AI systems — not how it would rank in a search results page.

Two design rules run through all eight categories:

• Weights shift by page type. A homepage is weighted toward entity and retrieval; an article is weighted toward answerability and citation. 14 page types are supported, each with its own weight profile merged over a shared default.
• Unknown is never zero. If a signal genuinely can't be measured — no date on the page, no target query supplied, no author byline where one isn't expected — it's excluded from the weighted average and its weight is redistributed across what was actually measured, rather than counted against the page.

An optional LLM pass (Claude, via the same Anthropic client the fix agents' orchestrator can use) can enhance a handful of the semantic sub-scores by reading a content excerpt. That result is blended with the deterministic score rather than replacing it, and the entire pipeline works correctly with use_ai=False.

07 Page type classificationPART 1

Before any AI Readiness scoring happens, each page is classified into one of 14 types (homepage, article, product, documentation, forum, review, organization, and so on) using a deterministic vote across URL structure, schema.org types already present, and content-structure signals like link density and heading patterns — no LLM call, so it runs on every page instantly.

This classification is what lets the scoring system avoid two common mistakes: penalizing a homepage for not answering FAQ-style questions, and penalizing a documentation page for missing Product schema it was never going to have.

08 InterfacesPART 1

The audit engine is exposed through a Gradio app with three primary actions:

All three share the same underlying async functions (run_seo_analysis_fastapi,run_full_seo_audit, run_ai_visibility_analysis), so nothing is fetched or rendered twice per run.

09 How a fix run worksPART 2

A fix run is triggered from a single form (or a direct POST) and executes as one sequential pipeline per repository, starting from the CSV the audit engine produced.

10 Fix Agents APIPART 2

POST /run — form fields

The request blocks for the duration of the run (10-minute server-side timeout) and returns the orchestrator's return code, stdout, and stderr as JSON.

// response shape
{
  "returncode": 0,
  "stdout": "...",
  "stderr": "...",
  "success": true
}

11 CSV handoff contract

This is the exact shape Part 1 exports and Part 2 expects — one row per URL. If you're feeding the fix agents a CSV from somewhere other than the audit engine, matching this schema is what makes it work.

The audit engine's export includes many additional columns (Core Web Vitals, AI Readiness sub-scores, redirect chains, and so on) for reporting purposes — the fix agents simply ignore any column they don't need.

12 Environment variables

13 Write safety & idempotencyPART 2

Every file write goes through the same guard rails, regardless of which agent is writing:

• Marker-scoped blocks. Generated content lives between explicit start/end markers (ONPAGE-AUTO-FIX, TECHNICAL-CANONICAL) so a second run replaces its own output instead of duplicating it.
• Truncation guard. safe_write refuses to overwrite a file if the model's output is empty or suspiciously shorter than the original — the original file is kept and the failure is logged, not silently swallowed.
• Single JSX root. Schema injection locates the component's actual return statement by scanning for the largest balanced-parenthesis span, rather than assuming the first or last return ( in the file — this avoids corrupting early guard clauses or helper functions.
• Client component awareness. Files starting with "use client" are skipped for server-only metadata exports, since that syntax is invalid there.

14 Supported stacks

The audit engine (Part 1) works against any live, publicly reachable site regardless of stack — it never touches source code. The per-page fix agents (Part 2) need a repo it recognizes to know where to write.

15 Roadmap