Metadata-Version: 2.4
Name: georankpy
Version: 0.1.3
Summary: Developer-first GEO (Generative Engine Optimization) toolkit — make your website visible to AI systems like ChatGPT, Claude, Gemini, and Perplexity.
Project-URL: Homepage, https://github.com/akash-nathai/georankpy
Project-URL: Documentation, https://dmpa.space/georankpy
Project-URL: Repository, https://github.com/akash-nathai/georankpy
Project-URL: Issues, https://github.com/akash-nathai/georankpy/issues
Author-email: Akash Nath <hello@akashnath.in>
License: MIT License
        
        Copyright (c) 2025 Akash Nath
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai-optimization,ai-visibility,chatgpt,generative-engine-optimization,geo,llm,llms-txt,perplexity,semantic-analysis,seo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: lxml>=5.2.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: all
Requires-Dist: django>=4.2.0; extra == 'all'
Requires-Dist: flask>=3.0.0; extra == 'all'
Requires-Dist: spacy>=3.7.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: django
Requires-Dist: django>=4.2.0; extra == 'django'
Provides-Extra: flask
Requires-Dist: flask>=3.0.0; extra == 'flask'
Provides-Extra: nlp
Requires-Dist: spacy>=3.7.0; extra == 'nlp'
Description-Content-Type: text/markdown

# GeoRankPy 🌐🤖

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

[![PyPI](https://img.shields.io/pypi/v/georankpy)](https://pypi.org/project/georankpy/)
[![Python](https://img.shields.io/pypi/pyversions/georankpy)](https://pypi.org/project/georankpy/)
[![CI](https://github.com/akash-nathai/georankpy/actions/workflows/ci.yml/badge.svg)](https://github.com/akash-nathai/georankpy/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 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

```bash
pip install georankpy
```

With spaCy NLP entity extraction:
```bash
pip install georankpy[nlp]
python -m spacy download en_core_web_sm
```

With Flask integration:
```bash
pip install georankpy[flask]
```

With Django integration:
```bash
pip install georankpy[django]
```

---

## Quick Start

### Python API

```python
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

```bash
# 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

```python
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:**
```html
<meta name="ai-optimized" content="georankpy" data-version="0.1">
```
```
X-GEO-Optimized: georankpy/0.1
```

---

## Django Integration

**settings.py:**
```python
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:**
```python
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

```python
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

- [x] Core crawler + parser
- [x] Semantic analyzer
- [x] Entity extraction (rule-based + spaCy)
- [x] GEO scoring engine
- [x] llms.txt generator
- [x] Flask integration
- [x] Django integration
- [x] CLI (typer + rich)
- [x] 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](CONTRIBUTING.md) first.

```bash
git clone https://github.com/akash-nathai/georankpy
cd georankpy
pip install -e ".[dev]"
pytest tests/ -v
```

---

## License

MIT — see [LICENSE](LICENSE).

---

## Citation

If you use GeoRankPy in research, please cite:

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

---

*Built by [Akash Nath](https://akashnath.in) other profiles [Akash Nath RG](https://www.researchgate.net/profile/Akash-Nath-4) [Akash Nath ai linkedin](https://www.linkedin.com/in/akashnathai/) [Akash Nath GITHUB](https://github.com/akash-nathai)*
