angeo/module-ai-description-updater

Automatically generate and update Magento 2 product descriptions across all store views using AI — via CLI, cron, or Admin Panel.

angeo/module-ai-description-updater is an open-source Magento 2 module for bulk AI-powered product description generation across multiple store views and languages. Supports OpenAI, Anthropic Claude, Google Gemini, and Groq (free, no credit card required). Results can be exported to Google Sheets automatically.

Table of contents

• Why this module vs alternatives
• Supported AI providers
• Requirements
• Installation
• Quick start — Groq (free, 5 minutes)
• Full configuration reference
  • General
  • AI Provider
  • OpenAI settings
  • Claude settings
  • Gemini settings
  • Groq settings
  • Prompt
  • Attributes
  • Google Sheets — SKU source
  • Google Sheets — export
  • Export / CSV
  • Cron
• CLI usage
• Multi-store behaviour
• Setup guides
  • OpenAI API key
  • Anthropic Claude API key
  • Google Gemini API key
  • Groq API key (free)
  • Google Sheets — SKU source setup
  • Google Sheets — export setup (Service Account)
• Log file
• Related modules

Why this module vs alternatives

Supported AI providers

Requirements

• PHP 8.1 – 8.5
• Magento 2.4.x / Adobe Commerce / Mage-OS
• ext-curl, ext-openssl

Installation

composer require angeo/module-ai-description-updater
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Quick start — Groq (free, 5 minutes)

The fastest way to get started — Groq is free with no credit card required.

Step 1 — Get a free API key

Go to console.groq.com, create an account, go to API Keys → Create API key. The key starts with gsk_.

Step 2 — Configure Magento

Go to Stores → Configuration → Angeo AEO → AI Description Updater:

1. General → Enable Module → Yes
2. General → Dry Run Mode → Yes (safe for first test)
3. AI Provider → AI Provider → Groq (Free — Llama / Mixtral)
4. Groq Settings → Groq API Key → paste your gsk_... key
5. Groq Settings → Model → Llama 3.3 70B Versatile (recommended)
6. Attributes → Generate Description → Yes
7. Click Save Config

Step 3 — Test with dry-run

bin/magento angeo:ai-description:run --dry-run

Check var/log/angeo_ai_description_updater.log to preview what would be generated.

Step 4 — Run on a single product first

Disable Dry Run in admin, then:

bin/magento angeo:ai-description:run --sku=YOUR-TEST-SKU

Verify the result in the product edit page. If it looks good, run the full batch:

bin/magento angeo:ai-description:run

Full configuration reference

Path: Stores → Configuration → Angeo AEO → AI Description Updater

General

AI Provider

Only the selected provider's settings section is used. Switch providers at any time.

OpenAI settings

Used when AI Provider is set to OpenAI.

Claude settings

Used when AI Provider is set to Anthropic Claude.

Gemini settings

Used when AI Provider is set to Google Gemini.

Note: If you get limit: 0 errors, create a new Google Cloud project and generate a fresh API key.

Groq settings

Used when AI Provider is set to Groq.

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

Prompt

Example prompt template:

Write a professional and SEO-friendly product description for "{{product_name}}"
(SKU: {{product_sku}}) for our {{store_name}} online store.
Include key benefits, features, and use cases.
Format using HTML paragraphs. Keep it between 150 and 250 words.

Attributes

Tip: Enable meta attributes only after validating description quality. Test with --dry-run first.

Google Sheets — SKU source

Use a Google Spreadsheet as the source of SKUs to process instead of all active products.

No Service Account required — the spreadsheet must be set to "Anyone with the link can view".

See Google Sheets SKU source setup for step-by-step instructions.

Google Sheets — export

Write generated descriptions back to a Google Spreadsheet after each run.

See Google Sheets export setup for step-by-step instructions.

Export / CSV

When Google Sheets — export → Enable is on, the saved CSV is also uploaded to Google Drive via the configured Service Account, in addition to the structured Sheets export.

Batching and cost control

Each run processes at most Batch Size SKUs per store view (including when the SKU source is Google Sheets). A per-store offset is persisted in var/angeo/ai_description_updater/offset_store_<id>.txt, so consecutive runs advance through the catalogue instead of repeatedly re-processing the first N products. The offset wraps back to the start once the whole catalogue has been covered. This keeps AI API spend bounded and predictable.

To reset progress for a store, delete its offset file.

Cron

CLI usage

# Run for all active store views
bin/magento angeo:ai-description:run

# Single SKU across all stores
bin/magento angeo:ai-description:run --sku=MY-SKU-001

# Single store view only
bin/magento angeo:ai-description:run --store=2

# Dry-run — generate but do not save
bin/magento angeo:ai-description:run --dry-run

# Combine options
bin/magento angeo:ai-description:run --sku=MY-SKU --store=2 --dry-run

Multi-store behaviour

When run without --store, the module processes every active non-admin store view sequentially.

For each store view:

• Product is loaded in that store's scope
• Per-store configuration (prompt template, language, enabled attributes) is read in that store view's scope — set different prompts or languages per store view and they are honoured
• Generation runs inside store-area emulation so store-scoped settings resolve correctly
• {{store_name}} in the prompt is replaced with the store view name
• Generated content is saved in that store's scope — not the global default scope

# List your store IDs
bin/magento store:list

# Run for a specific store only
bin/magento angeo:ai-description:run --store=3

Setup guides

OpenAI API key

1. Go to platform.openai.com → sign in or create account
2. Click your profile → API keys → Create new secret key
3. Copy the key — shown only once (starts with sk-)
4. In Magento: Stores → Configuration → Angeo AEO → AI Description Updater → OpenAI Settings → API Key

Add a payment method at platform.openai.com/account/billing for production use.

Anthropic Claude API key

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

Google Gemini API key

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

If you get limit: 0 errors: create a new Google Cloud project and generate a new key there.

Groq API key (free)

1. Go to console.groq.com → create account — no credit card required
2. API Keys → Create API key
3. Copy the key (starts with gsk_)
4. In Magento: ... → Groq Settings → API Key

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

Google Sheets — SKU source setup

Step 1 — Create the spreadsheet

Create a new spreadsheet at sheets.google.com. Add SKUs in column A, one per row:

SKU
MY-SKU-001
MY-SKU-002
MY-SKU-003

Step 2 — Make it publicly readable

Share → Change to anyone with the link → Viewer → Done

Step 3 — Get the Spreadsheet ID

Copy the ID from the URL:

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms/edit
                                       ↑ this is the Spreadsheet ID

Step 4 — Configure in Magento

• Enable → Yes
• Spreadsheet ID → paste ID
• Sheet GID → 0 (first tab) or ?gid= value from URL for other tabs
• SKU Column Index → 0 for column A

Google Sheets — export setup (Service Account)

Step 1 — Create a Google Cloud project

Go to console.cloud.google.com:

1. Click the project dropdown (top left) → New Project
2. Name it (e.g. angeo-sheets) → Create

Step 2 — Enable Google Sheets API

Left menu → APIs & Services → Library → search Google Sheets API → Enable

Step 3 — Create a Service Account

Left menu → IAM & Admin → Service Accounts → Create Service Account:

1. Choose Application data when asked what data you will access
2. Service account name: angeo-ai-updater
3. Click Create and Continue → skip optional role → Done

Step 4 — Generate a JSON key

Click the service account → Keys tab → Add Key → Create new key → JSON → Create

A JSON file downloads automatically. It looks like this:

{
  "type": "service_account",
  "project_id": "angeo-sheets",
  "client_email": "[email protected]",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n",
  "token_uri": "https://oauth2.googleapis.com/token"
}

Copy the client_email value — you need it in the next step.

Step 5 — Share the spreadsheet with the Service Account

1. Create a new spreadsheet at sheets.google.com
2. Click Share
3. Paste the client_email from the JSON (e.g. [email protected])
4. Set role to Editor
5. Click Send

Step 6 — Configure in Magento

Go to Stores → Configuration → Angeo AEO → AI Description Updater → Google Sheets Export:

1. Enable → Yes
2. Service Account JSON → paste the entire contents of the downloaded JSON file
3. Spreadsheet ID → copy from the spreadsheet URL
4. Sheet Tab Name → Sheet1 (or your tab name)
5. Clear Sheet Before Write → Yes to overwrite, No to append
6. Save Config

Verify:

bin/magento angeo:ai-description:run --sku=ONE-SKU --dry-run

Dry-run does not export. Disable dry-run and run again — a row should appear in the spreadsheet.

Log file

# Watch in real time
tail -f var/log/angeo_ai_description_updater.log

# Last 50 lines
tail -50 var/log/angeo_ai_description_updater.log

Log entries include: run start/complete, per-SKU status (updated / dry_run / error), AI API errors, Google Sheets export result.

Related modules

Security

This module treats AI output and external data sources as untrusted:

• Stored XSS protection — content generated for the HTML description attribute is passed through a whitelist HTML sanitiser before saving. Only a safe subset of formatting tags is kept; <script>, event-handler attributes (onerror, onclick, …) and javascript: URLs are stripped.
• CSV / formula injection protection — every cell written to a CSV export is escaped (values starting with =, +, -, @ are prefixed with '). The Google Sheets export uses valueInputOption=RAW, so values are never evaluated as formulas server-side.
• SSRF hardening — the Google Sheets CSV fetch is restricted to docs.google.com over HTTPS only, with bounded redirects that may not downgrade to non-HTTPS targets. Spreadsheet/Drive IDs are validated against [A-Za-z0-9_-].
• Path-traversal protection — the CSV filename pattern is reduced to a safe basename.
• CSRF — admin controllers are POST-only (HttpPostActionInterface), so Magento enforces the admin form key.
• Secrets — all API keys and the Service Account JSON are stored encrypted (backend_model = Encrypted) and never written to logs.
• Error handling — admin endpoints return generic messages; full exception detail goes to the dedicated log only.

If you discover a security issue, please email [email protected] rather than opening a public issue.

License

MIT — free to use, modify, and distribute.

Author

Ievgenii Gryshkun · angeo.dev · [email protected]

Changelog

All notable changes to angeo/module-ai-description-updater are documented here.
This project adheres to Semantic Versioning.

[1.1.1] - 2026-09-16

Code-quality release. Generated descriptions do not change.

Fixed

• Removed all curl_close() calls. The function does nothing since PHP 8.0
  and is deprecated in PHP 8.5, where Magento's error handler would turn the
  deprecation into an exception on every AI provider or Google call.

Changed

• PHP 8.1–8.5 (was >=8.2). The code uses no PHP 8.2+ syntax or
  functions. Magento dependencies have bounded ranges for Magento
  2.4.6 – 2.4.x instead of *.
• AttributeConfig is no longer final (Magento coding standard).
• Product status filter uses ['eq' => …]. Same SQL.
• phpunit.xml no longer lists the non-existent Test/Integration suite;
  phpstan.neon replaced with the suite-wide config.

Build

• Unit tests: the Google Sheets test covered a column-expression parser that
  no longer exists; it now covers CSV parsing and the SSRF host check.
  phpunit.xml drops an attribute PHPUnit 10.5 rejects and the coverage
  report that failed CI without a coverage driver.
• GitHub Actions CI (.github/workflows/ci.yml) on PHP 8.1–8.5: composer
  validate, PHP lint, Magento2 coding standard,
  PHPUnit. PHPStan runs once, in its own job on PHP 8.2, as in
  the Mage-OS modules. Magento
  packages come from the Mage-OS mirror.
• phpstan.neon (level 5, bitexpert/phpstan-magento). The extension
  generates Magento factory classes during analysis, so no stub files are
  needed.
• Dev tooling: PHPUnit 10.5, PHPStan 2, magento/magento-coding-standard
  ^40 || ^41.

Documentation

• README: one badge row across the suite — CI, Packagist version and
  downloads, PHP 8.1 – 8.5, supported Magento range, Mage-OS Extension
  Directory, license.

Quality

• Magento2 coding standard: 0 errors. PHPStan level 5: no errors.

[1.1.0] - 2026-06-13

Security

• Stored XSS (critical) — AI output for the HTML description attribute was
  saved unsanitised. Added Service\Security\HtmlSanitizer, a whitelist-based
  sanitiser (allowed tags/attributes only; strips <script>, event handlers and
  javascript: URLs). AiProviderService::postProcess() now sanitises all HTML
  attributes before they are stored.
• CSV / formula injection (critical) — CSV export wrote raw values, and the
  Google Sheets export used valueInputOption=USER_ENTERED, allowing values such
  as =IMPORTXML(...) to execute on open / server-side. Added
  Service\Security\SpreadsheetValueSanitizer (prefixes = + - @ with ') for
  CSV, and switched the Sheets export to valueInputOption=RAW.
• SSRF / blind redirect — GoogleSheetsService::downloadCsv() now restricts
  requests to docs.google.com over HTTPS only, with CURLOPT_PROTOCOLS /
  CURLOPT_REDIR_PROTOCOLS set to HTTPS, bounded redirects, and TLS verification
  enforced. The full sheet URL is no longer written to the log.
• Spreadsheet/Drive ID validation — IDs are validated against
  ^[A-Za-z0-9_-]{10,}$ before use in URLs.
• Path traversal — the CSV filename pattern is reduced to a safe basename and
  stripped of unsafe characters.
• CSRF hardening — both admin controllers now implement
  HttpPostActionInterface (POST-only), so the admin form key is enforced.
• Information disclosure — admin controllers return generic error messages;
  full exception detail is logged only.
• Drive query escaping — findExistingFile() escapes \ and ' correctly
  for the Drive query language instead of using addslashes().

Added

• Run-summary email notification (Notify Email) via TransportBuilder and
  a new angeo_ai_description_summary email template — previously documented but
  not implemented.
• Google Drive CSV upload is now wired into the run: when Sheets export is
  enabled, the generated CSV is also uploaded via the Service Account
  (GoogleDriveService was previously dead code).
• Per-store batch offset tracking: each run processes at most batch_size
  SKUs per store and advances a persisted offset, so the whole catalogue is
  eventually covered instead of always re-processing the first N products.
• Unit tests for HtmlSanitizer and SpreadsheetValueSanitizer.

Changed

• Per-store prompts/language now actually apply. Generation runs inside store
  area emulation and reads getEnabledAttributes() / buildPromptForAttribute()
  / getSystemRole() in the current store-view scope (previously always the
  default scope).
• Bounded memory on large catalogues. SKU resolution uses a SKU-only product
  collection (addAttributeToSelect('sku')) instead of fully hydrating every
  product via getList()->getItems().
• The Google Sheets SKU source now also respects batch_size (previously it
  processed all SKUs with no cap).
• str_getcsv() is called with explicit separator, enclosure and escape
  arguments to avoid the PHP 8.4 deprecation.
• CSV/offset directory created with 0750 permissions instead of 0755.

Fixed

• fopen() failure in CSV export is now checked and handled.

[1.0.0] - 2026-05-16

• Initial release: OpenAI, Anthropic Claude, Google Gemini and Groq providers;
  Google Sheets SKU source; Google Sheets export; dry-run mode; per-store prompts;
  CLI and cron automation.