AgriciDaniel/jev-seo

Live SEO audit for any website from one homepage URL, judged by Jev. PDF, XLSX and Markdown reports.

What is jev‑seo?

jev‑seo is a Python tool that performs a live SEO audit of any website from just its homepage URL. It crawls the site, checks it against a set of 52 Google‑recommended rules, measures Core Web Vitals via PageSpeed Insights, and then asks Jev – TypeSafe’s “System One” LLM – a series of typed questions about each page (e.g., page type, search intent, helpfulness). The answers are scored, prioritized, and turned into three ready‑to‑share reports:

  • PDF – a client‑friendly document with a cover, executive summary, scorecard, charts, and actionable recommendations.
  • XLSX – an editable action tracker where each fix has an ID, priority, impact, effort, and source.
  • Markdown – a GitHub/Obsidian‑friendly version with embedded charts.

The tool can run as a Claude Code skill (/jev‑seo https://example.com) or from the command line.

How it works (high‑level pipeline)

  1. Crawl – polite, respects robots.txt, follows sitemaps, records redirects, broken links, canonical tags, structured data, and can render JavaScript‑only pages with Playwright (optional).
  2. Rule check – applies 52 SEO rules covering crawlability, indexing, on‑page factors, structured data, performance, security, and AI‑crawler access.
  3. Core Web Vitals – pulls Lighthouse scores from Google PageSpeed Insights (free API).
  4. Jev judgments – sends typed prompts to the TypeSafe Jev model (≈ $0.00015 USD per page) to get probabilistic answers for 13 page‑level and 5 site‑level questions.
  5. (Optional) Full mode – enriches the audit with keyword rankings, traffic estimates, competitors, backlinks, and live SERP data from DataForSEO (≈ $0.30 USD per site).
  6. Scoring & ranking – combines rule results, Jev probabilities, and optional SEO data into a numeric score and a prioritized list of fixes.
  7. Report generation – a single audit.json powers the PDF (via WeasyPrint), Excel workbook, and Markdown output.

Key features

Feature Why it matters
Live crawl (not a static template) Guarantees the audit reflects the current state of the site, including JavaScript‑rendered content.
Jev‑driven judgments Adds a LLM‑based assessment of page intent, usefulness, trust, etc., with probabilities that are stored for transparency.
Ranked, explainable fixes Each recommendation includes an ID, priority, impact, effort, evidence, and a source link, making it easy to hand off to developers or content teams.
Three output formats from one source PDF for clients, XLSX for project tracking, Markdown for version‑controlled documentation.
Cost‑controlled API usage Built‑in caps (--jev-budget, --dfs-budget) and a cost ledger in the report keep spending predictable.
Optional DataForSEO enrichment Adds keyword opportunities, competitor analysis, and backlink data for a deeper SEO picture (paid).
Offline test suite Unit tests run without network calls, ensuring the core logic works without spending API credits.

Who might use it

  • SEO consultants who need a quick, reproducible audit to share with clients.
  • Web developers / product teams looking for a concrete, prioritized list of technical SEO fixes.
  • Content strategists interested in keyword and SERP insights (via the --full mode).
  • AI‑savvy marketers who want to see how an LLM (Jev) evaluates site quality and can incorporate those judgments into their workflow.

Getting started (quick steps)

# Clone & set up a virtual environment
git clone https://github.com/AgriciDaniel/jev-seo.git
cd jev-seo
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt

# Add your TypeSafe API key (optional for Jev, required for full mode)
cp .env.example .env   # edit .env and set TYPESAFE_API_KEY

# Run a basic audit
bin/jevseo run https://example.com

Optional: install Playwright for JavaScript rendering and DataForSEO credentials for the enriched mode.

Limitations & caveats

  • Sampling – Large sites are limited to a default page cap of 60; the report notes when sampling occurs.
  • Jev calibration – The LLM’s thresholds are not yet benchmarked against human SEO experts.
  • PageSpeed variance – Lighthouse scores can fluctuate between runs.
  • No traffic or ranking tracking – The tool is an evidence snapshot, not a rank‑tracker or analytics platform.

License

MIT‑licensed. Fonts bundled with the PDF are under the SIL Open Font License.

All information above is taken directly from the repository’s README; no external assumptions have been added.

Related

  • Project
    ajsahni/agents-office

    Agents Office is a beta, locally‑run visual platform that turns Claude into a team of 35 role‑based AI agents. You type tasks, the system routes them to the right agent (or a team), the agents use Claude Code connectors (Gmail, Slack, Chrome, etc.) to do the work, and results are saved as notes in your personal “Brain”. Features include customizable briefs/skills, recurring routines, a calendar view, team‑splitting, model/effort selection, and a non‑commercial license.

  • Project
    pmixer/SASRec.pytorch

    A PyTorch re‑implementation of the SASRec sequential recommendation model, with training/inference scripts for MovieLens‑1M and recent LayerNorm improvements.

  • Project
    antirez/qwen-asr

    A pure C implementation of the Qwen3-ASR inference pipeline for efficient speech-to-text transcription on CPU, NVIDIA, and AMD GPUs.

  • Project
    chenxiachan/thoughtdag

    ThoughtDAG is an open‑source desktop/web app that turns each LLM chat turn into a node on an infinite canvas. By connecting or disconnecting nodes (wires) you decide exactly which past turns become context for the next request, enabling branching, pruning, and merging of conversations. It includes a local index for searching past sessions, an optional Jev decision model for relevance ranking, a CLI for quick look‑ups, and a DeepSeek Harness plugin. Install via Homebrew, npm, or from source; configure any OpenAI‑compatible or Ollama endpoint. Features include document side‑by‑side clipping, condensing/weaving of paths, per‑node model selection, export of the graph as a “Thought Map”, and read‑only sharing. MIT‑licensed and actively maintained.