georankpy 0.1.0

Developer-first GEO (Generative Engine Optimization) toolkit — make your website visible to AI systems like ChatGPT, Claude, Gemini, and Perplexity.

GeoRankPy 🌐🤖

Generative Engine Optimization toolkit for Python developers.
Make your website visible to AI systems — ChatGPT, Claude, Gemini, Perplexity, RAG pipelines, and autonomous agents.

---

Why GeoRankPy?

Traditional SEO tools optimise for Google's crawlers. Modern AI systems — ChatGPT, Claude, Gemini, Perplexity — rely on semantic structure, entity clarity, chunk retrievability, and metadata quality.

GeoRankPy is the developer-first toolkit for this new layer.

What GeoRankPy provides	What existing tools provide
Python library + CLI	SaaS dashboards
Flask / Django middleware	WordPress plugins
llms.txt generation	llms.txt checking
Semantic chunk analysis	Keyword scoring
Entity extraction	Backlink tracking
Open-source, self-hosted	API subscriptions

---

Installation

pip install georankpy

With spaCy NLP entity extraction:

pip install georankpy[nlp]
python -m spacy download en_core_web_sm

With Flask integration:

pip install georankpy[flask]

With Django integration:

pip install georankpy[django]

---

Quick Start

Python API

from georankpy import audit, generate_llms_txt, analyze

# Full GEO audit
result = audit("https://example.com")
print(result.geo_score.geo_score)        # e.g. 74
print(result.geo_score.band)             # ScoreBand.GOOD
print(result.geo_score.issues)           # list of GeoIssue
print(result.geo_score.recommendations)  # actionable fixes

# Generate llms.txt only
llms = generate_llms_txt("https://example.com")
print(llms.content)  # save to /llms.txt on your server

# Semantic analysis only (faster)
report = analyze("https://example.com")
print(report.overall_score)   # 0.0–1.0
print(report.chunks)          # RAG-ready chunks

CLI

# Full audit
georank audit https://example.com

# Save report
georank audit https://example.com --format html --output report.html
georank audit https://example.com --format md   --output report.md

# Generate llms.txt
georank generate llms https://example.com
georank generate llms https://example.com --output llms.txt

# Semantic analysis only
georank analyze https://example.com

Example CLI output:

╭─────────────── 🔍 GEO Score — https://example.com ────────────────╮
│                  74/100  •  GOOD                                    │
╰────────────────────────────────────────────────────────────────────╯

 Score Breakdown
 ┌─────────────────────────┬───────┬─────┐
 │ Dimension               │ Score │ Max │
 ├─────────────────────────┼───────┼─────┤
 │ Semantic Clarity        │  18.5 │  25 │
 │ Metadata Completeness   │  17.0 │  20 │
 │ Chunk Retrievability    │  14.2 │  20 │
 │ Schema Quality          │  10.0 │  15 │
 │ Entity Richness         │   7.5 │  10 │
 │ llms.txt Quality        │   6.8 │  10 │
 └─────────────────────────┴───────┴─────┘

Issues:
  🟡 [MISSING_LLMS_TXT] No /llms.txt file found.
     → Run: georank generate llms https://example.com
  🔵 [WEAK_ANCHOR_SENTENCES] Most sections lack strong opening sentences.

---

Flask Integration

from flask import Flask
from georankpy.integrations.flask_ext import GEO

app = Flask(__name__)

geo = GEO(
    app,
    site_name="My App",
    site_description="A Python web application.",
)

# Manually register key pages for llms.txt
geo.add_route("/docs",  "Documentation", "Full API reference")
geo.add_route("/about", "About",         "About our team and mission")
geo.add_route("/blog",  "Blog",          "Technical articles and tutorials")

Auto-created routes:

• GET /llms.txt — AI-readable site summary
• GET /geo/score — JSON status endpoint
• GET /ai-sitemap.xml — AI-friendly sitemap

Auto-injected into every response:

<meta name="ai-optimized" content="georankpy" data-version="0.1">

X-GEO-Optimized: georankpy/0.1

---

Django Integration

settings.py:

INSTALLED_APPS = [
    ...
    "georankpy.integrations.django_ext",
]

MIDDLEWARE = [
    ...
    "georankpy.integrations.django_ext.middleware.GeoMiddleware",
]

GEORANKPY = {
    "SITE_NAME": "My Django App",
    "SITE_DESCRIPTION": "A Django-powered application.",
    "INJECT_META": True,
    "ROUTES": [
        {"path": "/",       "title": "Home",          "description": "Main page"},
        {"path": "/about/", "title": "About",         "description": "About us"},
        {"path": "/docs/",  "title": "Documentation", "description": "API docs"},
    ],
}

urls.py:

from georankpy.integrations.django_ext.urls import geo_urlpatterns

urlpatterns = [
    ...
] + geo_urlpatterns

---

Score Dimensions

Dimension	Max	What it measures
Semantic Clarity	25	Heading structure, chunk quality, readability
Metadata Completeness	20	Title, description, Open Graph, canonical
Chunk Retrievability	20	RAG-readiness of content sections
Schema Quality	15	JSON-LD structured data richness
Entity Richness	10	Named entities: people, orgs, technologies
llms.txt Quality	10	AI-readable site summary file
Total	100

---

Export Formats

from georankpy import audit
from georankpy.reports.formatter import save_html, save_json, save_markdown

result = audit("https://example.com")

save_json(result,     "report.json")
save_markdown(result, "report.md")
save_html(result,     "report.html")

---

Roadmap

• Core crawler + parser
• Semantic analyzer
• Entity extraction (rule-based + spaCy)
• GEO scoring engine
• llms.txt generator
• Flask integration
• Django integration
• CLI (typer + rich)
• JSON / Markdown / HTML reports
• Django management command (python manage.py geo_audit)
• Async crawler for multi-page audits
• Benchmark dataset + research paper
• Node.js SDK
• VS Code extension

---

Contributing

Contributions are very welcome! Please read CONTRIBUTING.md first.

git clone https://github.com/Hero777-tech/georankpy
cd georankpy
pip install -e ".[dev]"
pytest tests/ -v

---

License

MIT — see LICENSE.

---

Citation

If you use GeoRankPy in research, please cite:

@software{georankpy2025,
  author = {Nath, Akash},
  title  = {GeoRankPy: A Python Toolkit for Generative Engine Optimization},
  year   = {2025},
  url    = {https://github.com/Hero777-tech/georankpy}
}

---

Built by Akash Nath