Pythia

The oracle that tells you how AIs see your site.

Pythia is a local-first CLI that audits any webpage for GEO (Generative Engine Optimization) and AEO (Answer Engine Optimization) — making sure AI systems like ChatGPT, Claude, Perplexity, and Mistral can read, cite, and recommend your content.

No API key. No SaaS. No cloud account. Works on any public URL. Pipe it into CI/CD and fail the build if your GEO score drops below threshold.

pip install pythia-geo
pythia audit https://example.com

Why GEO matters

Traditional SEO optimizes for crawlers. GEO optimizes for large language models that summarize, answer, and cite web content directly in their responses. If your site isn't structured for AI comprehension, you're invisible to a growing share of user queries.

Pythia checks 14 signals across three categories:

Quick start

# Audit a URL, print Markdown report
pythia audit https://example.com

# JSON output for CI integration
pythia audit https://example.com --format json

# French output
pythia audit https://example.com --lang fr

# Fail if score < 80 (default threshold: 70)
pythia audit https://example.com --threshold 80

# Save report to file
pythia audit https://example.com --output report.md

# List all available checks
pythia list-checks

Exit code: 0 if score ≥ threshold, 1 otherwise.

CI/CD integration

# .github/workflows/geo-audit.yml
- name: GEO audit
  run: |
    pip install pythia-geo
    pythia audit https://yoursite.com --threshold 70 --format json --output geo-report.json

Sample output

# Pythia GEO Audit — https://example.com

Score: 74/100  ●●●●●●●○○○  ❌ FAIL (threshold: 70)

## STRUCTURE (40%)  —  32/100

- ✅ PASS `llms_txt_present` — llms.txt found and accessible
- ⚠️  WARN `llms_full_txt_present` — llms-full.txt not found (optional but recommended)
- ✅ PASS `robots_ai_bots` — No AI bots blocked in robots.txt
- ✅ PASS `sitemap_accessible` — Sitemap found and accessible
- ❌ FAIL `jsonld_present_valid` — No JSON-LD structured data found

## HTML (30%)  —  25/100

- ✅ PASS `single_h1` — Exactly one H1 found
- ✅ PASS `heading_hierarchy` — Heading hierarchy is sequential
- ✅ PASS `title_length` — Title length is within 30–65 characters
- ⚠️  WARN `meta_description` — Meta description present but length is outside 70–160 characters
- ❌ FAIL `opengraph_minimal` — No OpenGraph tags found

## CONTENT (30%)  —  17/100

- ✅ PASS `generic_headings` — No generic headings detected
- ⚠️  WARN `faq_pattern` — No FAQ structure found
- ✅ PASS `eeat_signals` — Author and publication date detected
- ❌ FAIL `structured_content` — No structured content found (no lists or tables)

## Recommendations

- **`jsonld_present_valid`** — Add <script type="application/ld+json"> with Organization or Article schema
- **`opengraph_minimal`** — Add og:title, og:description, og:type meta tags
- **`structured_content`** — Use <ul>, <ol>, or <table> to structure your content

Checks reference

AI bots checked by robots_ai_bots: GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot, MistralAI-User.

About the name

In ancient Greece, Pythia was the Oracle of Delphi — the high priestess of Apollo who delivered prophecies to kings, generals, and philosophers. Seekers traveled from across the Mediterranean to ask her questions and receive pivotal answers that shaped history.

Today, LLMs are the new oracles. Ask ChatGPT about a product, a concept, a brand — and it will answer with the confidence of a Delphic prophecy. Whether your site appears in that answer, and how accurately it's represented, depends entirely on how well your content speaks to these modern oracles.

Pythia ensures the oracle speaks your truth.

The name also fits the Kryptide ecosystem: kryptos (κρυπτός) means "hidden" in Greek — Pythia is the one who reveals.

Contributing

Issues and PRs welcome. See the project conventions in CLAUDE.md.

Commit messages follow Conventional Commits: feat:, fix:, docs:, test:, chore:.

License

MIT — see LICENSE.

pip install pythia-geo
pythia audit https://monsite.fr --lang fr