Metadata-Version: 2.5
Name: citeready
Version: 0.1.0
Summary: Can AI assistants read, trust and cite your business page? A deterministic, dependency-free audit: JSON-LD completeness, structured-data vs visible-page consistency, robots.txt vs AI crawlers, llms.txt
Project-URL: Homepage, https://github.com/GradeBuilderSL/citeready
Project-URL: Source, https://github.com/GradeBuilderSL/citeready
Project-URL: Issues, https://github.com/GradeBuilderSL/citeready/issues
Project-URL: Built by, https://laspi.pro/en
Author-email: "GradeBuilder S.L." <org@gradebuilder.tech>
License: MIT
License-File: LICENSE
Keywords: ai-visibility,audit,geo,json-ld,llms-txt,schema-org,seo,structured-data
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# citeready

[![CI](https://github.com/GradeBuilderSL/citeready/actions/workflows/ci.yml/badge.svg)](https://github.com/GradeBuilderSL/citeready/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/GradeBuilderSL/citeready/blob/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/citeready)](https://pypi.org/project/citeready/)
[![Python](https://img.shields.io/pypi/pyversions/citeready)](https://pypi.org/project/citeready/)

**Can AI assistants read, trust and cite your business page?**
Pure stdlib, zero dependencies, one command.

When someone asks ChatGPT-class assistants for "a good bakery nearby", the
answer is assembled from pages the assistant can actually *read*: structured
data, consistent contact details, plain crawlable HTML. `citeready` audits one
page the way an answer engine sees it and hands you a scored, explainable
report. Every check is a plain deterministic rule you can read in the source —
no model in the loop, no network calls beyond the page itself.

## Install

```
pip install citeready
```

## Usage

```
$ citeready https://vegabakery.example/
citeready — https://vegabakery.example/
score 96/100

Structured data
  ✓ JSON-LD structured data found (1 block)
  ✓ all JSON-LD blocks parse
  ✓ business node found (Bakery)
  ✓ name present
  ✓ address present
  ✓ telephone present
  ...
  ✓ phone matches the visible page

Page basics
  ✓ title: «Vega Bakery — sourdough & pastry in Valencia»
  ✓ meta description present
  ...

Site signals
  ✓ AI crawlers are not blocked
  ! no llms.txt (emerging, optional standard)
  ✓ sitemap.xml present
```

Also takes a local file (`citeready page.html`) or stdin (`citeready -`);
`--json` for machine-readable output, `--strict` to exit non-zero when any
check fails (handy in CI).

From Python:

```python
from citeready import audit

report = audit("https://vegabakery.example/")   # or audit(html_string)
report.score                                    # 0–100
[(f.check, f.level, f.message) for f in report.findings]
```

## What it checks

**Structured data** — the part assistants quote from:

- JSON-LD is present and parses (`@graph` handled)
- a business node exists (`LocalBusiness`/`Organization`/subtypes — `Bakery`,
  `BeautySalon`, `LegalService`, …)
- must-have properties: `name`, `address`, `telephone`, `url` (missing = fail)
- rich properties: `description`, `geo`, `openingHours`, `sameAs`, `image`,
  `priceRange` (missing = warn)
- **consistency**: the name, phone and street from structured data actually
  appear on the visible page — mismatched data reads as unreliable

**Page basics** — `title` (present, sane length), meta description, exactly
one `h1`, `lang` attribute, canonical URL, no `noindex`, Open Graph pair.

**Site signals** (URL mode) — `robots.txt` does not block AI crawlers
(GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot, …), `llms.txt`,
`sitemap.xml`.

Scoring is the plain weighted share: pass = 1, warn = ½, fail = 0, ×100.
No hidden weights, so two reports are always comparable.

## Honest limits

Static HTML only — no JavaScript is executed, so a page that renders its
content client-side will score poorly here. That is partly the point (most
answer-engine crawlers read static HTML too), but a low score on a
JS-heavy site deserves a manual look. Checks are heuristics with documented
thresholds, not a certification; `robots.txt` parsing is deliberately naive
(full-block detection, not path matching).

## Scope is frozen

This package does one thing: it audits a page and reports. Bug reports
(wrong counts, crashes on valid HTML, missed JSON-LD) are very welcome.
Feature requests — crawling whole sites, fixing what it finds, tracking
scores over time — are out of scope for now.

## Built to power Laspi

<a href="https://laspi.pro/en">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/GradeBuilderSL/citeready/main/assets/laspi-logo-dark.png">
    <img src="https://raw.githubusercontent.com/GradeBuilderSL/citeready/main/assets/laspi-logo-light.png" alt="Laspi" width="220">
  </picture>
</a>

`citeready` is the measuring half of the AI-visibility work inside
**[Laspi](https://laspi.pro/en)** — a marketing employee in a small-business
owner's phone. Laspi keeps a living memory of the business (every fact
confirmed by the owner), writes platform-native posts, images and short
videos from it, and looks after the business's visibility in AI answers —
in whatever language the business sells in. This audit is how that work
starts: measure first, then fix.

The measuring is open source. The fixing is the product: **[laspi.pro](https://laspi.pro/en)**.

## License

MIT © 2026 [GradeBuilder S.L.](https://laspi.pro/en)
