README

Live AI brand visibility audit for Magento 2 — queries ChatGPT, Claude, Perplexity, Gemini and Groq with brand-probing prompts and scores real-world AI recall, citation rate and recommendation presence.

angeo/module-aeo-brand-visibility is an open-source Magento 2 module that answers one question: when someone asks ChatGPT "where should I buy X?", does your store appear in the answer? It runs configurable prompts across all major AI providers, detects brand signals in responses, and scores your visibility from 0 to 100 with a letter grade.

What it measures
Supported AI providers
Requirements
Installation
Quick start
Admin Panel
CLI usage
Full configuration reference
- General
- AI Providers
- Query Prompts
- Scoring
- Cron
Setup guides
Scoring explained
How to improve your score
Integration with angeo/module-aeo-audit
Related modules

What it measures

Each AI query result is analysed for five signals:

Signal	Description
Mentioned	Your brand name appears in the AI response
Recommended	AI actively suggests your store as a destination
URL Cited	Your domain is included in the answer
1st Position	Your store is the first recommendation
Positive Sentiment	Response tone about your brand is positive

Each signal has a configurable weight. The overall score is a weighted average across all successful query results, converted to 0–100 and graded A–F.

Supported AI providers

Provider	Models	Cost	Notes
Groq	llama-3.3-70b-versatile, mixtral-8x7b	Free	Best starting point — 14,400 req/day, no card
Perplexity	sonar, sonar-pro, sonar-deep-research	Paid	Live web search — most realistic signal
OpenAI	gpt-4.1, gpt-4.1-mini, gpt-4o	Paid
Anthropic Claude	claude-sonnet-4-6, claude-haiku-4-5	Paid
Google Gemini	gemini-2.5-flash-preview, gemini-2.0-flash	Free tier + paid

Enable one or more providers. Each active provider runs all configured prompts, and results are aggregated into a single score.

Requirements

PHP 8.2+
Magento 2.4.x / Adobe Commerce / Mage-OS
angeo/module-aeo-audit ^2.0
ext-curl

Installation

composer require angeo/module-aeo-brand-visibility
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Quick start

Step 1 — Configure your brand

Go to Stores → Configuration → Angeo AEO → Brand Visibility → General:

Brand Name → your store name as AI systems know it (e.g. Angeo)
Brand Domain → your domain without protocol (e.g. angeo.dev)
Store Category → what you sell (e.g. Magento development tools)

Step 2 — Enable a free provider (Groq)

Go to Groq Settings:

Get a free API key at console.groq.com — no credit card
Enable Groq → Yes
Groq API Key → paste your gsk_... key
Save Config

Step 3 — Run your first audit

bin/magento angeo:aeo:brand-visibility

Or from Admin Panel: Marketing → Angeo AEO → Brand Visibility → Run Audit

Admin Panel

Marketing → Angeo AEO → Brand Visibility

Run Audit

The main dashboard with:

Score ring — overall score 0–100 with letter grade (A–F)
Signal breakdown — mention rate, recommendation rate, URL citation rate, 1st position rate, positive sentiment rate
Results table — per-provider, per-prompt responses with detected signals highlighted
Action plan — prioritised recommendations to improve your score
Single Query Tester — test one provider + one prompt without saving to history

Audit History

Grid view of all past audit runs with:

Date, brand, score (colour-coded), grade (badge), triggered by, query count, error count
Signal pills showing signal rates at a glance
Click any row action → View for full detail page with raw AI responses

Configuration

Stores → Configuration → Angeo AEO → Brand Visibility

CLI usage

# Full audit — all enabled providers, all enabled prompts
bin/magento angeo:aeo:brand-visibility

# Force fresh queries — bypass cache
bin/magento angeo:aeo:brand-visibility --refresh

# Test a single provider
bin/magento angeo:aeo:brand-visibility --provider=groq

# Test a single provider + specific prompt
bin/magento angeo:aeo:brand-visibility --provider=chatgpt --prompt=brand_direct

# Output as JSON (useful for CI pipelines)
bin/magento angeo:aeo:brand-visibility --format=json

# CI mode — exit code 1 if score below threshold
bin/magento angeo:aeo:brand-visibility --fail-on=70

Option	Values	Description
`--refresh` / `-r`	flag	Bypass cache, force live queries
`--provider`	`chatgpt` `claude` `perplexity` `gemini` `groq`	Test one provider only
`--prompt`	`recommendation` `category` `brand_direct` `product_search` `comparison` `gift_guide`	Test one prompt type only
`--format`	`table` `json` `markdown`	Output format. Default: `table`
`--fail-on`	`0`–`100`	Exit 1 if overall score is below this value

Full configuration reference

Path: Stores → Configuration → Angeo AEO → Brand Visibility

General

Field	Default	Description
Brand Name	(store name)	Your brand name as AI systems know it
Brand Domain	—	Your domain without protocol (e.g. `angeo.dev`). Used for URL citation detection.
Brand Keywords	—	Comma-separated aliases the AI may use to refer to your brand
Store Category	—	What you sell (e.g. `Magento 2 development tools`). Used in prompts.
Top Products / Services	—	Newline-separated product or service names for product search prompts
Cache Results (hours)	12	How long to cache audit results. `0` = always run live.
Enable Cron	No	Run automatically on a schedule

AI Providers

Each provider has its own section. Enable the ones you have API keys for.

ChatGPT (OpenAI)

Field	Default	Description
Enable ChatGPT	No
API Key	—	Starts with `sk-`. Stored encrypted.
Model	gpt-4.1	`gpt-4.1-mini` is fastest and cheapest.
Max Tokens	800	Maximum response length.
Request Timeout (s)	30

Claude (Anthropic)

Field	Default	Description
Enable Claude	No
API Key	—	Starts with `sk-ant-`. Stored encrypted.
Model	claude-sonnet-4-6	`claude-haiku-4-5` is fastest and cheapest.
Max Tokens	800
Request Timeout (s)	60

Perplexity

Field	Default	Description
Enable Perplexity	No
API Key	—	Stored encrypted.
Model	sonar	`sonar-pro` for deeper web search. `sonar-deep-research` for most thorough results.
Max Tokens	800
Request Timeout (s)	60	Perplexity performs live web searches — may be slower.

Note: Perplexity uses live web search, making it the most realistic indicator of actual AI visibility. It reflects what customers would see today, not what was in training data months ago.

Gemini (Google)

Field	Default	Description
Enable Gemini	No
API Key	—	Stored encrypted.
Model	gemini-2.5-flash-preview-05-20	`gemini-2.0-flash` has a free tier.
Max Tokens	800
Request Timeout (s)	30

Groq (Free)

Field	Default	Description
Enable Groq	No
API Key	—	Starts with `gsk_`. No credit card required.
Model	llama-3.3-70b-versatile	Best quality on free tier.
Max Tokens	800
Request Timeout (s)	30

Free tier: 30 RPM, 14,400 requests/day.

Query Prompts

Six prompt types are available. Enable or disable each individually.

Prompt Key	Example query sent to AI
`recommendation`	"What are the best online stores to buy [category]?"
`category`	"Where can I buy [category] online?"
`brand_direct`	"Tell me about [brand] — what do they sell and what is their website?"
`product_search`	"I'm looking for [top products] online. Which stores do you recommend?"
`comparison`	"Compare [brand] with other [category] stores online."
`gift_guide`	"Which online stores have the best [category] for gifts?"

Additional settings:

Field	Default	Description
Queries per Provider	3	How many prompts to run per enabled provider per audit
Delay Between Queries (ms)	500	Rate limiting delay between individual API calls
System Prompt	(default)	Instructions sent to each AI model before the query
Custom Prompts	—	Additional prompts, one per line, format: `key: prompt text`

Scoring

Signal weights determine the contribution of each detected signal to the overall score:

Signal	Default Weight
1st Position	2.0
Recommended	1.5
URL Cited	1.5
Mentioned	1.0
Positive Sentiment	0.5

Grade thresholds:

Score	Grade
90–100	A
75–89	B
60–74	C
40–59	D
0–39	F

Cron

Field	Default	Description
Enable Cron	No	Run audit automatically on a schedule
Schedule	`0 6 * * *`	Standard cron expression. Default: daily at 6:00 AM.

Results from cron runs appear in Audit History with triggered_by: cron.

Setup guides

Groq API key (free)

Go to console.groq.com — create an account, no credit card required
API Keys → Create API key
Copy the key (starts with gsk_)
In Magento: Stores → Configuration → Angeo AEO → Brand Visibility → Groq Settings → API Key

OpenAI API key

Go to platform.openai.com → sign in or create account
API keys → Create new secret key
Copy the key (starts with sk-) — shown only once
In Magento: ... → ChatGPT Settings → API Key

Anthropic Claude API key

Go to console.anthropic.com → create account
API Keys → Create Key
Copy the key (starts with sk-ant-)
In Magento: ... → Claude Settings → API Key

Google Gemini API key

Go to aistudio.google.com/app/apikey
Create API key in new project
Copy the key
In Magento: ... → Gemini Settings → API Key

Perplexity API key

Go to perplexity.ai/settings/api
Generate → copy the key
In Magento: ... → Perplexity Settings → API Key

Scoring explained

Each AI query produces a BrandQueryResult with five boolean signals. Signals are weighted and averaged:

query_score = sum(signal_weight for each detected signal) /
              sum(all_signal_weights) * 100

The overall score is the average of all successful query scores. Failed queries (API errors) are excluded from the average.

Example with default weights:

1st Position detected → +2.0
Recommended detected → +1.5
URL Cited not detected → 0
Mentioned detected → +1.0
Positive Sentiment detected → +0.5

query_score = (2.0 + 1.5 + 1.0 + 0.5) / (2.0 + 1.5 + 1.5 + 1.0 + 0.5) * 100
            = 5.0 / 6.5 * 100 = 76.9 → Grade B

How to improve your score

Signal missing	Root cause	Fix
Not mentioned	AI has no knowledge of your brand	Publish content that AI systems crawl: Dev.to, Reddit, GitHub
URL not cited	Domain not in AI training data or live index	Install `angeo/module-llms-txt` to give AI systems a structured map of your site
Not recommended	No authority signals in AI-accessible content	Add Product and Organization JSON-LD via `angeo/module-rich-data`
Not 1st position	Competitors have stronger AI presence	Increase external mentions: guest posts, Packagist downloads, GitHub stars
Negative sentiment	Poor reviews or negative coverage	Address public feedback; ensure AI-crawlable content is positive

Run bin/magento angeo:aeo:audit for a full 8-signal technical AEO audit to identify and fix the infrastructure issues that block AI indexing.

Integration with angeo/module-aeo-audit

When angeo/module-aeo-audit is installed (required dependency), this module adds a brand_visibility checker to the AEO audit pipeline.

# Full 9-signal audit including brand visibility
bin/magento angeo:aeo:audit

Brand visibility appears as signal #9 with pass/warn/fail status based on your configured score threshold.

Related modules

Module	Purpose
`angeo/module-aeo-audit`	8-signal CLI audit — checks AI technical indexing signals
`angeo/module-llms-txt`	Auto-generates llms.txt and llms.jsonl
`angeo/module-rich-data`	Product, Organization, FAQPage JSON-LD schema
`angeo/module-openai-product-feed`	ChatGPT Shopping product feed
`angeo/module-ai-description-updater`	Bulk AI product description generation

License

MIT — free to use, modify, and distribute.

Author

Ievgenii Gryshkun · angeo.dev · info@angeo.dev

angeo / module-aeo-brand-visibility

Maintainers

Package info

Statistics

Security