catalogready-ai 0.6.0

Open-source product-data readiness checker for AI shopping

CatalogReady

Can AI shopping agents actually read your product page?

CatalogReady is the open-source Lighthouse for AI shopping. Point it at a product page and get a transparent 0–100 readiness score, the exact product data machines can and cannot read, unsupported marketing claims, and paste-ready fixes.

Offline · deterministic rules · no API key · never writes to your store.

uvx --from catalogready-ai catalogready https://your-store.com/products/example

  Waterproof Commuter Shoe – Blue

  CatalogReady Score: 82/100 (ready)

  Product identity      16/20
  Offer completeness    20/20
  Structured data       20/20
  Decision evidence     14/15
  Media & variants       2/15
  Claim grounding       10/10

  0 critical · 2 recommended · 0 minor findings
  Full report: catalogready-report.html

The HTML report is a single self-contained file: score dial, per-pillar breakdown, every finding with a stable rule ID, the questions only the merchant can answer, a recommended Product JSON-LD block built strictly from evidence found on the page, and a downloadable PNG score card.

Why this exists

ChatGPT shopping, Google AI results, and Perplexity buy-flows read product pages with machines, not eyes. A page can look perfect to humans while being invisible or untrustworthy to an AI shopping agent: missing stable IDs, incomplete offers, absent Product JSON-LD, and marketing claims with no supporting evidence.

CatalogReady checks what the machines check — deterministically, locally, and with a score that survives scrutiny:

• Only your page earns points. Nothing CatalogReady generates contributes to the score.
• Blocking defects cap the score. Duplicate IDs, incomplete offers, missing structured data, or an unsupported high-risk claim hard-cap the number, no matter how complete everything else is.
• Every finding cites evidence and carries a rule ID you can grep for. docs/RULES.md documents every rule with its source — Google's merchant-listing requirements, OpenAI's Agentic Commerce feed spec, Bing's Copilot grounding guidelines, and the published crawler documentation of OpenAI, Perplexity, and Anthropic.

See docs/scoring-methodology.md for the full rubric and caps.

Install and run

# one-off (recommended for a first try)
uvx --from catalogready-ai catalogready https://your-store.com/products/example

# or as a checkout
uv sync
uv run catalogready audit https://your-store.com/products/example

# fully offline: audit a saved page instead of fetching it
uv run catalogready audit https://your-store.com/products/example saved-page.html

# machine-readable output
uv run catalogready audit <url> [saved.html] --json

Fetching is exactly one HTTP GET for the page you name. The audit engine itself makes no network calls — the test suite runs with networking disabled.

Try it on the bundled examples without touching the network:

uv run catalogready audit https://example.com/products/cr-001 examples/demo-store/index.html
uv run catalogready catalog examples/messy-apparel.csv   # scores 51/100, and shows exactly why

What gets checked

Pillar	Examples of rules
Product identity	stable ID (SKU/GTIN/MPN), brand, category, canonical URL
Offer completeness	price + currency + availability, complete Offer markup
Structured data	Product JSON-LD present, valid, consistent with the visible page
Decision evidence	description, specifications, shipping/returns/care/limitations on the page
Media & variants	primary image, image count, variant attributes and identity
Claim grounding	superlatives, “clinically proven”, warranty and performance claims checked against page evidence

When facts are missing, CatalogReady asks instead of inventing: the report lists the questions only the merchant can answer, and --answers merchant-answers.json resumes the audit with verified values.

Interactive agent session

catalogready chat opens a Claude Code-style terminal session over the bounded agent — audit, ask, answer, fix:

catalogready> /audit https://your-store.com/products/example
● inspect_product_page — Extracted 3 evidence items ...
● audit_product — Measured readiness at 16/100 and produced 13 findings.

  CatalogReady Score: 16/100 (needs_work)
  ...
  [blocking] price: What is the current verified product price?

catalogready> why is offer completeness low?
Offer completeness: 0/20
  ✗ price
  ✗ currency
  ...

catalogready> /answers sku=CR-100 price=49.00 currency=AUD availability=in_stock
catalogready> /draft
Isolated preview validation: 16 → 60 (+44), status validated.

catalogready> /report

The agent pauses for facts it cannot verify instead of inventing them; /answers resumes it. Free-text questions are answered deterministically from the audit result; set /provider openai (or gemini, claude, deepseek — keys via server environment variables only) for open-ended, model-answered questions grounded strictly in the audit JSON.

Interactive dashboard

One command serves the web UI and the local API on the same port and opens your browser:

uv run catalogready dashboard

Enter a product URL and press Audit — the local server fetches the page for you (one request). Or paste the HTML / load the built-in good/bad demos to stay fully offline. Every audit produces a plain-language summary conclusion, auto-drafted fix suggestions with an isolated preview validation, expandable per-pillar score explanations, inline merchant questions, a paste-ready JSON-LD patch, an "Ask the agent" chat window, and a downloadable HTML report. The UI follows your browser language (English / 中文, switchable in the header). Everything runs locally; the page never asks for API keys.

Use it with ChatGPT, Claude, Gemini, Copilot, or DeepSeek

CatalogReady ships an MCP server, so the AI assistant you already use can audit pages as a tool:

claude mcp add catalogready -- uv run catalogready-mcp

docs/QUICKSTART-AI-ASSISTANTS.md has copy-paste setups for ChatGPT/Codex, Claude (Code + Desktop), Gemini (CLI + Enterprise A2A), Copilot (VS Code agent mode), and DeepSeek — covering both directions: the assistant calling CatalogReady as a tool, and each vendor as the optional BYO model inside CatalogReady. Protocol details: docs/INTEROPERABILITY.md.

How it compares

	CatalogReady	Google Rich Results Test	Generic SEO crawlers	AI copy generators
Validates Product schema syntax	✓	✓	partial	✗
Scores completeness for AI shopping agents	✓	✗	✗	✗
Checks marketing claims against evidence	✓	✗	✗	✗
Runs offline, no account, no API key	✓	✗	✗	✗
Hands you a paste-ready JSON-LD fix	✓	✗	✗	generated, ungrounded

Bring your own model key (optional)

Everything above runs with no key. To enable model-assisted planning, chat answers, and listing drafts, put a provider key in the server's .env — see docs/BYO-KEYS.md. Keys never enter the dashboard, the extension, or tool arguments.

Also in the box

The audit engine is a vendor-neutral service with several thin surfaces. These are secondary to the page audit and documented in docs/ROADMAP.md:

• catalogready catalog feed.csv — CSV catalog audit with the same deduction-and-cap scoring.
• catalogready-api — HTTP server with OpenAPI docs and an A2A agent card.
• A Chromium extension (browser-extension/) — one click on any product page captures the rendered HTML and shows the score, findings, merchant questions, auto-drafted fixes, and the ask-the-agent box. Works on bot-protected storefronts because it reads what your browser rendered.
• Optional model-assisted listing drafts (OpenAI, Gemini, Claude, DeepSeek) with bring-your-own keys via server environment variables — never in tool arguments or browser storage — and deterministic claim evaluation with publishing safety caps.

Guarantees

• The deterministic core requires no API key and makes no network calls.
• CatalogReady never writes to a storefront, feed, or merchant system.
• It never invents product attributes, citations, or rankings.
• A readiness score is not a promise of ranking or citation by any AI system — and any tool that promises that is guessing.

Contributing

Rule proposals are the most valuable contribution — see CONTRIBUTING.md and the issue templates. Run the suite with python -m unittest discover -s tests -v; it must pass offline.

Architecture and module design: docs/repository-design.md · Rules with sources: docs/RULES.md · Scoring: docs/scoring-methodology.md · Interoperability: docs/INTEROPERABILITY.md · Roadmap: docs/ROADMAP.md

Contact

Built by Vincent Po Li. Questions, fix help, partnership, or feedback:

• Issues / discussions: github.com/PO-VINCENT/ai-shopping-audit
• Email: [e-mail]
• LinkedIn: vincent-po-li
• X: @Vincent_Po_Li
• 小红书 (Xiaohongshu): vincent726217

Licensed under Apache-2.0.