# AI Personal Shopper Documentation

Installation steps and a complete reference for every setting, with concrete examples — the same level of detail our support uses to help customers.

## Installation

### Requirements

Magento 2.4.x — tested on 2.4.9, compatible with previous 2.4.* releases. PHP 8.1–8.5. Compatible with both the default Luma theme and the Hyvä theme (the chat widget renders in an isolated Shadow DOM, so it looks identical on both, with no template changes). Depends on the free `codingrow/module-core` module, installed automatically. Requires an API key from at least one AI provider (OpenAI, Anthropic, Google or OpenRouter) — the AI usage is billed to you directly by the provider, Codingrow never marks it up.

### Setup steps

1. Add the credentials you'll receive by email to `auth.json` in your Magento project root:
   ```json
   { "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } }
   ```
2. `composer config repositories.codingrow composer https://repo.codingrow.com`
3. `composer require codingrow/module-ai-personal-shopper`
4. `bin/magento module:enable Codingrow_AiPersonalShopper`
5. `bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush`
6. Paste your license key into **Admin → Stores → Configuration → Codingrow → AI Personal Shopper → License → License Key**, save, then flush the cache.

### Configuration

**Stores → Configuration → Codingrow → AI Personal Shopper.**

| Setting | What it does | Default | Notes |
|---|---|---|---|
| **License Key** | The license key issued for this domain. | — | Accepts a single-module key or a Codingrow subscription key. Without a valid license the chat widget does not render. |
| **Enable** | Turns the chat widget on for the storefront. | No | Requires a valid license and at least one AI provider API key. |
| **AI Models** (separate tab) | Which provider serves the conversation (OpenAI, Anthropic, Google, OpenRouter), the model, and the API key. | — | **Not on this page**: they live in *Codingrow → AI Personal Shopper → AI Models*, the only place the chat reads them from. The *AI Provider* group that used to sit here was removed in 2.1.0 — its fields no longer had any effect. |
| **Agent limits → Max tool rounds** | How many times per message the agent may query catalog and orders before answering. | 4 | 1 to 8. Higher = more accurate but slower and costlier. |
| **Assistant & Branding** | Assistant/operator name, greeting, launcher label/position, accent color, header/theme color, company logo or name, extra tone-of-voice instructions. | — | The operator name still shows as a sub-line under your brand when a logo/company name is set. |
| **Capabilities** | Toggles: product search, order status, promotions, add-to-cart, voice input, self-learning synonyms, human support tickets. | — | Disable anything you don't want the agent to do. |
| **Catalog Search** | Max products per reply, in-stock only, and whether sold-out choices are shown greyed out. | 8 / Yes / Yes | *Show unavailable choices* is about the options **inside** a product (sizes, colours, kit items); *Only in-stock products* decides whether the product is proposed at all. |
| **Proactive assistant** | Whether the assistant may start the conversation itself, after an add to cart or when a visitor is idle. | Off | Everything off by default; the chat window never opens by itself. |
| **Human support** | Support email (BCC), response time text, ticket number prefix, auto-close after N days, notify customer on resolve. | 24-48 hours | Only used when the **Human support tickets** capability is on. |
| **Privacy** | Conversation retention, in days. | — | Older conversations are purged by a daily task; bug reports are kept until removed manually. |

### Uninstallation

Set **Enable** to **No** and save to hide the widget immediately. To remove the module entirely: `bin/magento module:disable Codingrow_AiPersonalShopper` then `composer remove codingrow/module-ai-personal-shopper`.

## Choosing an AI provider and getting an API key

The assistant works with any of four providers — you bring your own key, and the AI usage is billed to you directly by the provider you pick.

### OpenAI (ChatGPT / GPT models)

1. Sign in at [platform.openai.com](https://platform.openai.com).
2. Go to **[platform.openai.com/api-keys](https://platform.openai.com/api-keys)**.
3. Click **Create new secret key**, name it (e.g. "AI Personal Shopper"), and copy it immediately — it is shown only once.
4. Add it as a new AI on the **AI Models** tab (*Codingrow → AI Personal Shopper → AI Models*) with **Provider** set to OpenAI, then use **Load models** to pick the model.

### Anthropic (Claude models)

1. Sign in at [console.anthropic.com](https://console.anthropic.com).
2. Go to **[console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)**.
3. Click **Create Key**, name it, and copy the value.
4. Add it as a new AI on the **AI Models** tab (*Codingrow → AI Personal Shopper → AI Models*) with **Provider** set to Anthropic, then use **Load models** to pick the model.

### Google (Gemini models)

1. Sign in at [aistudio.google.com](https://aistudio.google.com) with a Google account.
2. Go to **[aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey)**.
3. Click **Create API key**, choose or create a Google Cloud project, and copy the key.
4. Add it as a new AI on the **AI Models** tab (*Codingrow → AI Personal Shopper → AI Models*) with **Provider** set to Google, then use **Load models** to pick the model.

### OpenRouter (one key, many providers' models)

1. Sign in at [openrouter.ai](https://openrouter.ai).
2. Go to **[openrouter.ai/keys](https://openrouter.ai/keys)**.
3. Click **Create Key**, name it, and copy the value.
4. Add it as a new AI on the **AI Models** tab (*Codingrow → AI Personal Shopper → AI Models*) with **Provider** set to OpenRouter, then use **Load models** to pick the model.

### Load models — no model id to type

After the API key is in place, save the section (or use the on-page action if available) and click **Load models** under the Model field: the module calls the provider's own model-list endpoint with your key and fills a dropdown with every model your key can actually use — pick from the list instead of typing an id. A manual text input remains available as a fallback for a model id that isn't in the list yet. A link right below the field always points to the correct key page for whichever provider is currently selected.

## User guide

### Capabilities

Each capability is an independent toggle under **Capabilities**: product search, order status lookup, promotions, add-to-cart, voice input, self-learning synonyms, human support tickets. Turning a capability off removes that ability from the agent immediately — for example, disabling **Human support tickets** means the agent will never propose opening a ticket, only **Self-learning synonyms** governs whether unmatched searches get recorded.

### Sizes, colours and kits (since 2.2.0)
The chat cart no longer accepts simple products only. When a product has choices to make, the assistant
offers them one at a time inside the conversation, and the product goes to the cart with the right
variant.

- **Configurable** — size first, then colour, then quantity, in the order the attributes are configured
  in Magento. Combinations that do not exist are never offered.
- **Grouped (kits)** — all items at once, each with its own quantity; anything left at zero does not end
  up in the cart.
- **Bundle (modular sets)** — one choice per option, optional add-ons included.

Choices are drawn the way you configured them in Magento: colours with their real hex code, sizes as a
large readable value, long lists as a dropdown. The quantity appears on the last card of the path. On
desktop everything happens in the side panel, on mobile inside the chat. On bundle and grouped cards the
price is the real range, not €0.00.

**Sold-out options stay visible, greyed out** — that is the default, because hiding a sold-out size makes
the customer believe you never make it. Switch: *Stores → Configuration → Codingrow → AI Personal Shopper
→ Catalog Search → Show unavailable choices, greyed out*. Options that can still be ordered are never
greyed. Not to be confused with *Only in-stock products*, which decides whether the product is proposed
at all.

If a product has custom options the chat cannot handle (a free-text engraving, a file upload), the
assistant says so and offers the link to the product page.

### Proactive assistant (since 2.2.0)
*Stores → Configuration → Codingrow → AI Personal Shopper → Proactive assistant.* Everything is off to
begin with, and the chat window never opens by itself: the assistant lights the dot on the button and
waits.

- **Suggest pairings after an add to cart** — *Never* (default), *only the first time in a visit*, or
  *every time*. When a customer adds something to the cart from the shop, the assistant prepares a couple
  of pairings. Each time is one AI call, billed by your provider. No waiting time here: it fires
  immediately and appears when the model answers.
- **Offer help after (seconds on the page)** — 0 = never (default). If a customer has been on a page that
  long without ever opening the chat, it offers a hand. This costs nothing: the sentence is written by the
  widget. Never on the cart or the checkout.
- **What it says** — the invitation text; empty means the default sentence, translated.

Works on Hyvä and Luma alike: the widget listens to the cart events the theme already emits, so an AJAX
add with no page reload is detected too. Conversations started this way skip the name ritual and are
recognisable in the console by the **Origin** column.

### Branding and colors

Set an **Assistant name** (shown as the operator, e.g. "Anna") and, optionally, a **Brand logo** (fixed height so it never deforms) or **Brand text** with your company name — shown top-left in the chat header. The operator name still appears as a sub-line with a live presence dot underneath the brand, even when a logo is set. **Accent color** controls the launcher button and in-chat accents; **Header/theme color** (optional) colors the header bar and the customer's message bubbles — leave it empty to reuse the accent color.

### Self-learning synonyms

When enabled (**Capabilities → Self-learning synonyms**), the agent records a mapping every time a customer's search word doesn't match the catalog directly but a later attempt does — regional names, dialect, misspellings, synonyms. Review and edit the registry in **Codingrow → AI Personal Shopper → Synonyms**: a paginated, inline-editable table. Use **Export CSV** / **Import CSV** to back it up, bulk-edit, or move it between environments. The **Inject into site search** button writes the whole registry into Magento's native **Search Synonyms**, so the storefront search bar benefits from what the agent has learned — not just the chat. The agent also reads your hand-curated native Search Synonyms, so both systems reinforce each other.

### Human support tickets

When enabled (**Capabilities → Human support tickets**), the agent proposes opening a ticket if a customer needs a human and isn't resolved by the conversation alone. It asks for **email** (required) and, when useful, **order number** and a **phone/WhatsApp** contact, then assigns a **ticket number** and emails the full transcript to the customer, **BCC'd** to the address set in **Human support → Support email (BCC)** (if left empty, the email goes only to the customer). The **response time** text shown to the customer comes from **Human support → Response time** (default "24-48 hours"). Tickets appear under the **Tickets & Support** tab: a grid with **View** opening the contact details and full transcript, a **mark resolved** action (with an optional notification email back to the customer), and an automatic **auto-close** after the number of days set in **Human support → Auto-close after (days)**. The agent also classifies conversations that report a site problem as **Bug report**, so issues reach your team without a support ticket.

| Setting | What it does | Default |
|---|---|---|
| **Support email (BCC)** | Address that receives a BCC copy of every ticket transcript email. | — (customer-only if empty) |
| **Response time** | Text shown to the customer when a ticket is opened. | 24-48 hours |
| **Ticket number prefix** | Prefix used when assigning ticket numbers. | — |
| **Auto-close after (days)** | Tickets with no activity are closed automatically after this many days. | — |
| **Notify customer on resolve** | Sends the customer an email when a ticket is marked resolved from the admin. | Off |

### Reading conversations

**Codingrow → AI Personal Shopper → Conversations** lists every conversation, automatically classified as **Shopping**, **Support**, **Bug report**, **Possible spam** or **Other**, paginated and filterable by type. The **View** action opens the full thread — every customer and assistant message, including the product cards proposed at each turn — read-only. Conversations can be deleted individually or in bulk; older conversations beyond the configured retention are purged by a daily task (bug reports are excluded from automatic purging).

### License

The license is issued for one domain and can be a **single-module** key (AI Personal Shopper) or a **Codingrow subscription** key (all modules). Without a valid license the chat widget does not render. Updates are included within the same major version.

---
© Codingrow (a brand of Revera SRLS). Sold worldwide. Licensed per domain.