Metadata-Version: 2.4
Name: causabi-geo
Version: 0.2.1
Summary: Fix how AI search engines see your website
Project-URL: Homepage, https://causabi.com
Project-URL: Repository, https://github.com/SHADRINMMM/causabi-geo
Project-URL: Documentation, https://causabi.com/for-developers
License: MIT
License-File: LICENSE
Keywords: ai,chatgpt,geo,llm,llms-txt,perplexity,schema,seo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.25
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Provides-Extra: ai
Requires-Dist: google-generativeai>=0.8; extra == 'ai'
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://causabi.com"><img src="https://img.shields.io/badge/causabi.com-free%20score-black?style=flat-square" alt="causabi.com" /></a>
  <a href="https://pypi.org/project/causabi-geo/"><img src="https://img.shields.io/pypi/v/causabi-geo?style=flat-square&color=blue" alt="PyPI" /></a>
  <a href="https://pypi.org/project/causabi-geo/"><img src="https://img.shields.io/pypi/pyversions/causabi-geo?style=flat-square" alt="Python" /></a>
  <img src="https://img.shields.io/github/license/SHADRINMMM/causabi-geo?style=flat-square" alt="MIT" />
</p>

<h1 align="center">causabi-geo</h1>
<p align="center"><b>CLI that checks and fixes how AI crawlers see your website</b></p>

---

**What this is.** A local, open-source CLI that audits a single page for AI-crawler readiness (robots.txt rules, Schema.org, FAQ markup, content depth, NAP signals, freshness) and generates ready-to-deploy fix files. No account, no server, MIT.

**Quickstart:**

```bash
pip install causabi-geo
geo-optimizer analyze https://yourdomain.com
```

(`causabi-geo analyze ...` works as an alias since v0.2.1.)

**Scope.** One-off local checks are free here, forever. Continuous work — scheduled re-checks, score history, monitoring of how 4 AI engines (ChatGPT, Claude, Gemini, Grok) actually answer questions about your brand, and reports — runs on [causabi.com](https://causabi.com).

---

## Example output

```
AI Readiness Score: 52/100  Grade C

  Category       Score   Max
  robots.txt        11    20
  Schema.org        15    25
  FAQ Schema         0    20
  Content           15    15
  Brand / NAP        4    10
  Freshness          7    10

Issues to fix:
  GPTBot is blocked from crawling your site
  No FAQPage schema — citation rate is 41% lower without it
  Missing NAP signals: phone, address
```

## What it fixes

Run `geo-optimizer fix https://yourdomain.com --output ./geo-fixes` and get:

| File | What it does |
|------|-------------|
| `robots.txt` | Your current robots.txt patched to allow 10 AI crawlers (GPTBot, ClaudeBot, PerplexityBot, CCBot, Google-Extended and more) |
| `schema.json` | Organization JSON-LD built from your page data |
| `llms.txt` | Site summary in the proposed llms.txt format (note: vendor adoption of llms.txt is not confirmed) |
| `faq-schema.json` | FAQPage JSON-LD — only generated with `--api-key` (Gemini) |
| `HOW-TO-APPLY.md` | Step-by-step guide to deploy each file |

## Install & usage

```bash
pip install causabi-geo

# Analyze
geo-optimizer analyze https://yourdomain.com
geo-optimizer analyze https://yourdomain.com --json
geo-optimizer score https://yourdomain.com        # alias for analyze

# Fix (generates ready-to-deploy files)
geo-optimizer fix https://yourdomain.com
geo-optimizer fix https://yourdomain.com --output ./out

# Fix with AI-generated FAQ (requires a Gemini API key)
geo-optimizer fix https://yourdomain.com --api-key YOUR_GEMINI_KEY
```

Get a free Gemini API key at [aistudio.google.com](https://aistudio.google.com).

## Scoring

| Category | Max | Signal |
|----------|-----|--------|
| robots.txt | 20 | Are AI crawlers blocked? (GPTBot, ClaudeBot, PerplexityBot, CCBot, Google-Extended, Bytespider, YouBot, cohere-ai, ia_archiver, anthropic-ai) |
| Schema.org | 25 | Organization / LocalBusiness / SoftwareApplication JSON-LD and how complete it is |
| FAQ Schema | 20 | FAQPage JSON-LD present, 3+ Q&A pairs |
| Content depth | 15 | Word count across crawled pages |
| Brand / NAP | 10 | Business name, phone, address, email, social links found on the page |
| Freshness | 10 | dateModified/datePublished in schema, or current-year mentions in content |

The score measures crawlability and machine-readability. It does not guarantee citations — no tool can.

Research behind the checks: [Princeton GEO paper (2023)](https://arxiv.org/abs/2311.09735) · [Digital Bloom citation study](https://www.digitalbloom.agency/research) (FAQ markup associated with +41% citation rate).

## Full platform

The CLI analyzes a single page, once, locally. **[causabi.com](https://causabi.com)** adds the continuous part:

- Multi-page crawl
- Scheduled re-checks and score history
- Monitoring of answers from 4 AI engines: ChatGPT, Claude, Gemini, Grok
- AI-generated fixes and reports
- Free first audit, no credit card

## License

MIT — see [LICENSE](LICENSE)
