Install and set up
Thanks for your purchase! Your licence key is in your Polar account. You'll need it in step 1.
Get my licence keyAbout 15 minutes. You need SSH access to the server, a database administrator who can create a MySQL user, and an API key from an AI provider.
1. Install with Composer
Use your licence key as the password. It's in your Polar account: follow the link in your purchase e-mail, or open polar.sh/gaurav-extensions/portal and sign in with the e-mail you bought with.
composer config repositories.aireports composer https://wuetygwpupwjhospscwi.supabase.co/functions/v1/composer
composer config http-basic.wuetygwpupwjhospscwi.supabase.co licence YOUR-LICENCE-KEY
composer require gauravharsh/module-ai-reports:^3.0
bin/magento module:enable Gaurav_AiReports
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush
Keep auth.json out of version control. On deployment pipelines, set the key as the COMPOSER_AUTH environment variable instead.
2. Create the read-only database user
CREATE USER 'aireports_ro'@'%' IDENTIFIED BY 'a-strong-random-password';
GRANT SELECT ON your_database_name.* TO 'aireports_ro'@'%';
FLUSH PRIVILEGES;
Restrict '%' to your application servers where you can.
3. Add it to app/etc/env.php
'aireports' => [
'readonly_connection' => [
'username' => 'aireports_ro',
'password' => 'a-strong-random-password',
],
],
The tool refuses to run until this is set. The credential can't be seen or changed in the admin.
4. Configure
Go to Stores › Configuration › Gaurav Extensions › AI Reports:
- Licence: paste your licence key.
- AI Connection: provider, API key and endpoint. For Anthropic use
https://api.anthropic.com/v1/messages. - Answer Quality: the model for each preset. The defaults are Claude Sonnet 5.5 for Quick and Claude Opus 5.5 for Standard and Thorough.
- Usage & Budget: set a monthly budget and a daily limit per person.
- Security Guardrails: review them, then set Enable Query Tool to Yes.
5. Build the store snapshot
bin/magento aireports:knowledge:build
This takes seconds to a few minutes. A weekly cron job keeps it fresh, and a daily check rebuilds it early when attributes, stores or the schema change.
6. Give people access
| Permission | Allows |
|---|---|
| AI Reports query | Asking questions and running saved reports |
| AI Reports knowledge | Rebuilding the snapshot and editing business rules |
| AI Reports query log | The audit log and usage figures |
| AI Reports configuration | The settings above |
Anyone with query access can read every non-blocked table across all websites. Grant it only to roles that may see that data.
Business rules
Under Reports › AI Knowledge, write down anything the database can't reveal, like a new analyst briefing. Name tables, attribute codes and ids where you know them. For example:
Product visibility depends on customer group. Listings and search only show products whose attribute customer_groups contains the shopper's group id. Guests are group 0. "Not showing for trade customers" usually means the trade group id is missing.
Copy rules between environments with:
bin/magento aireports:knowledge:rules export rules.json
bin/magento aireports:knowledge:rules import rules.json
Measure accuracy on your store
Write questions with known answers into a JSON file and score the AI against them. It shows the estimated cost and asks before it runs.
bin/magento aireports:eval:run --file=questions.json --preset=standard
Licence
- The key is checked once a day and when the settings page is saved. Check it now with
bin/magento aireports:licence:check. - The tool keeps working if the check fails, the server can't be reached, or the licence has expired.
- Local, test and staging domains never count towards your limit.
- To move a licence to another domain, contact support.
Updating
composer update gauravharsh/module-ai-reports
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush
Coming from 2.x: add the repository and key from step 1, then raise your constraint from ^2.0 to ^3.0.
What leaves your server
| Sent | To |
|---|---|
| Store structure: attributes and options, store and category names, order statuses, table and column names, your business rules | Your AI provider |
| The question as typed | Your AI provider |
| Answer mode only: up to 20 rows per query, with personal data masked | Your AI provider |
| Licence key, store domain, module and Magento versions | Us, once a day |
Never sent: blocked tables, credentials or full result sets. Table + CSV mode sends no rows.