A download-and-run, fully rule-based SEO analysis tool. It crawls a website you are authorized to analyze, evaluates it against a large versioned SEO rules repository (no generative AI, no AI/LLM APIs), produces a transparent, explainable score, builds a persistent per-project audit repository, and tracks historical SEO health over time.
Crawler → Rules Engine → Evidence → Diagnosis → Prioritization → Recommendation → Repository → Historical Analysis
No installation steps required. The first run automatically creates an isolated
environment (.venv/), installs the small dependency set, and then runs the app.
Everything (repository + reports) is stored locally next to this project.
| Operating system | Command |
|---|---|
| Windows (double-click or cmd) | run.bat <command> [options] |
| PowerShell | ./run.ps1 <command> [options] |
| macOS / Linux / WSL | ./run.sh <command> [options] |
| Any OS (driver) | python run.py <command> [options] |
Examples (all of them work identically):
./run.sh demo # offline demo + full audit
./run.sh audit https://example.com --name "My site" # audit a real site
./run.sh history 1 # trends after re-runs
./run.sh report 1 --format all # HTML + JSON + CSVrun.bat demo
run.bat audit https://example.com --name "My site"
run.bat report 1 --format htmlTip: on macOS / Linux / WSL you may need to make the script executable once:
chmod +x run.sh
| Typical "SEO checker" | This tool |
|---|---|
| Scans the homepage, returns a magic score | Crawls the real site (internal links + sitemaps), captures redirect chains, status codes, timing, structured data, on-page & content signals |
| Generic "add meta descriptions" tips | Deterministic rules that quantify how many pages, which URLs, why it matters, and exactly what to change |
| One-shot, no memory | Every run is stored as an audit inside a local SQLite repository; re-run and see new / fixed / reappeared / worsening / improving / unchanged issues |
| Opaque score | Every point is attributed to a rule (critical 22, major 11, minor 5) with a clickable breakdown in reports |
| Proprietary data lock-in | Open JSON / CSV / HTML / SQLite exports; the repository is a plain .sqlite3 file you own |
- Respects
robots.txt(RFC 9309 longest-match, Allow/Disallow with wildcards,$, crawl-delay) — toggle with--ignore-robots - Discovers pages via internal links and XML sitemaps (index + gzip,
sitemap_index.xmlprobes) - Captures the full redirect chain, status code, headers, response time, and content length per URL
- Extracts: titles, meta descriptions, meta robots, canonicals,
prev/next, headings (H1-H6), links + anchor text, images (alt/srcset/dims), JSON-LD/microdata, Open Graph, Twitter cards, hreflang, language, viewport, visible-text shingles for duplicate detection - Optional Playwright renderer (
--render-js) for JS-rendered content (pip install -e ".[browser]",python -m playwright install chromium)
Classifies each site into e-commerce, blog, SaaS, news, local business, documentation, marketplace, corporate using URL patterns, on-page text, and schema.org types — then activates the right rules (e.g. Product schema checks only run on commerce sites).
Every rule carries: unique ID, category, severity, priority, description, detection logic, SEO impact, recommendation, implementation instructions, examples, exceptions, version, and confidence. Categories:
- Technical — HTTP/HTTPS, redirect chains & loops, robots.txt, sitemaps, meta robots, 4xx/5xx, mixed content, URL casing & parameters, mobile viewport, JS-rendered content
- On-page — duplicate/missing/length titles, duplicate/missing/length meta descriptions, H1/heading hierarchy, Open Graph, Twitter cards, image alt & dimensions
- Content — thin content (per-vertical word floors), exact duplicates, near-duplicates (shingle Jaccard), keyword cannibalization, topic coverage
- Internal linking — orphans, broken links, deep pages
- Structured data — missing/invalid JSON-LD, Product/LocalBusiness/Breadcrumb schema, schema-vertical mismatches
- Performance — slow responses, oversized HTML, missing compression (Core Web Vitals proxies)
- International / Local / Commerce — hreflang reciprocity & x-default, NAP presence, faceted URL management
Six components (technical, on-page, content, internal linking, performance, structured data). Each starts at 100; each finding deducts a recorded penalty. Reports show exactly which rule produced each deduction.
SQLite-backed per-project portfolio of audits storing projects, audits, pages,
page meta, link graph, findings, rule results, score components, robots.txt
snapshots and sitemap snapshots. Re-running the same URL appends a new audit;
seo-engine history classifies each rule's trajectory.
Self-contained HTML audit report (executive summary, clickable score drill-downs, critical issues, high-priority opportunities, all findings, historical comparison), plus JSON, CSV, and SQLite backup.
Requires Python 3.10+ (developed on 3.14).
cd <this directory>
python -m pip install -e .
# optional: real-browser JS rendering
python -m pip install -e ".[browser]"
python -m playwright install chromiumDependencies (all local, no AI/network services): httpx, click, beautifulsoup4.
python -m seo_engine audit https://example.com \
--name "My project" \
--max-pages 500 \
--max-depth 12The crawl respects robots.txt, discovers the sitemap, extracts page evidence,
runs all rules, scores the site, and stores Audit #1 in ./seo-repository/.
python -m seo_engine demoThis starts a local demo site on http://127.0.0.1:8127/, immediately audits
it end-to-end, and saves the result.
python -m seo_engine audit https://example.com # Audit #2, #3, ...
python -m seo_engine history 1 # trends: new / fixed / reappeared / worsening / improving / unchanged
python -m seo_engine projects # list projects
python -m seo_engine audits 1 # list audits of project 1python -m seo_engine report 1 --format html --out ./reports
python -m seo_engine report 1 --format json --out ./reports
python -m seo_engine report 1 --format csv --out ./reports
python -m seo_engine report 1 --format all --out ./reports
python -m seo_engine backup --out ./backups # full SQLite repository copyAll commands accept --repo <dir> to point at a different repository location
(default: ./seo-repository).
python -m seo_engine --help
| Command | Purpose |
|---|---|
audit <url> |
Crawl, classify, run rules, score, save to repository |
demo |
Serve the bundled demo site and audit it immediately |
projects |
List repository projects |
audits <project_id> |
List a project's audits |
history <project_id> |
Historical trend analysis (new/fixed/reappeared/...) |
report <audit_id> |
HTML / JSON / CSV report |
backup |
Full SQLite backup |
Options on audit: --repo, --name, --max-pages, --max-depth,
--render-js, --obey-robots/--igore-robots, --concurrency, --no-save.
- Six categories, each starts at 100.
- Every rule finding deducts a penalty by severity: critical 22, major 11, minor 5, info 1 points, scaled by affected URL count (capped at 5 findings per rule per category).
- The overall score is a weighted average: technical 25%, on-page 20%, content 15%, performance 15%, structured data 15%, internal linking 10%, renormalized over measured categories.
- In HTML reports, each category card lists every contributing rule, its penalty and its finding count — click the score to see the rules behind it.
./seo-repository/seo-repository.sqlite3 # your data (single portable file)
Tables: projects, audits, pages, page_meta, page_links, findings,
rule_results, score_components, robots_snapshots, sitemap_snapshots,
exports, meta.
run.py, run.bat, run.ps1, run.sh # universal one-command launchers (any OS)
seo_engine/
__main__.py, cli.py # CLI entry points
config.py # settings
pipeline.py # crawl -> classify -> rules -> score -> repository
crawler/ # http client, robots, sitemap, html parser, BFS crawler, browser
rules/ # rule base + registry + technical / onpage / content / links /
# structured / performance / international / local / commerce (49 rules)
classify.py # deterministic site vertical detection
scoring.py # transparent weighted scoring
repository.py # SQLite persistence
history.py # trend intelligence (new/fixed/reappeared/...)
exports.py # HTML / JSON / CSV / backup
demo_site.py # bundled offline demo website
tests/ # pytest suite (unit + e2e against the demo site)
scripts/ # smoke tests & CLI workflow validator
python -m pytest tests/ -q # 22 tests: unit + e2e (demo server, repo, history, exports)Continuous integration (GitHub Actions) runs the full suite, the CLI workflow smoke test, and a packaging check on every push and pull request.
Released under the MIT License.