AI features

The shape, in one diagram

Mining job          → emits raw association rules (deterministic)
        ↓
Scoring             → ranks by profit-aware metrics (deterministic)
        ↓
Proposal generator  → picks bundle candidates (deterministic)
        ↓
AiTaskQueue         → enqueues LLM tasks (bundle copy, email copy, etc.)
        ↓
ProcessAiQueue cron → drains queue every minute via AiPromptDispatcher
                      ├── ai_catalog rule generation
                      ├── BundleCopyGenerator     → product name/description/SEO
                      ├── EmailCopyGenerator      → digest + abandoned-cart copy
                      ├── SessionIntentClassifier → tags storefront sessions
                      └── B2bAccountIntelligence  → account-level insights

The four AI features

1. AI catalog pairing (engine)

The ai_catalog engine solves the cold-start problem. Sends a bounded slice of the catalog to Claude with a structured JSON-output prompt: “Given these products, return a list of natural complement pairs with a 0–1 confidence score and a one-sentence rationale.” The dispatcher validates the JSON shape; malformed responses are logged and the engine emits an empty rule set rather than crashing the job.

2. Bundle copy generation

After you approve a bundle proposal, the catalog product is created in Draft. BundleCopyGenerator enqueues a task to generate the bundle's name, marketing description, and SEO meta — grounded on the component SKUs, their categories, the discount %, and your brand voice setting. The task runs async via ProcessAiQueue so bundle creation never blocks on the provider being available.

3. Session-intent classification

For storefronts that wire up the storefront-intel snippet, MBA classifies each session as browsing, comparing, ready-to-buy, or returning-customer based on the session's click trail and cart events. Used to gate which widgets render (e.g. Complete the Kit only fires for comparing + ready-to-buy sessions to avoid annoying browsers).

4. B2B account intelligence

For Magento B2B installs only. B2bAccountIntelligence summarizes the last-N orders for a given Company in plain English — purchase rhythm, top categories, growth/decline signal, and surfaces the summary in the company-detail admin. Useful for sales reps who want context before a check-in call without learning the schema.

The dispatcher: one class, four call sites

Every LLM-using service in the module goes through AiPromptDispatcher, which centralizes:

1. Feature-flag check (per-feature scope value)
2. Provider resolution via AiClientFactory
3. “Is the API key configured?” check
4. sendPrompt() with the HttpRetryTrait backoff (exponential, jittered, max 3 attempts)
5. Response parsing (JsonResponseParser for structured output; trim for text)
6. Uniform “log warning, return null” failure path

Every method returns null on any failure path — feature disabled, no API key, transport error, malformed response. Callers fall back to their templated / cached / empty defaults without branching on dozens of error types.

The queue: async by default

Most AI calls land in mba_reports_mbaaitask via AiTaskQueue::enqueue(). The cron job mba_reports_process_ai_queue runs every minute, atomically claims pending tasks (UPDATE … SET status='running' WHERE status='queued'), and routes each task to its handler by task_type:

• bundle_copy → BundleCopyHandler
• session_intent → SessionIntentClassifier
• b2b_intel → B2bAccountIntelligence
• email_copy → EmailCopyGenerator

Successful tasks are marked done; failures increment attempts and are retried until a configurable max, after which they're marked failed and surfaced in the admin. The retention setting purge_aitask_days (default 7) keeps the table from growing unbounded.

Providers

Two providers ship today, behind one interface (AiClientInterface):

• Anthropic Claude (ClaudeClient), the default. Uses /v1/messages with structured output for JSON-shaped tasks.
• OpenAI (OpenAiClient), chat-completions API with JSON-mode for structured tasks. Useful if your security review only blesses one vendor.

Pick the provider in store config (Magento) MBA Reports → AI → Provider or in WooCommerce MBA → Settings → AI. Per-call token caps are decoupled from the global max-tokens setting, long-context tasks (catalog mining, B2B intel) can ask for more headroom without bumping the cap for short tasks.

Configuration

Cost control

• The dispatcher caches successful responses for identical prompts (e.g. bundle copy for the same SKU set) for the retention window, re-running the same job doesn't re-bill.
• Tasks are batched where the provider supports it (Claude message batching for catalog mining).
• Per-feature flags above let you turn off any AI feature without losing the deterministic mining pipeline.
• Standard Pro on every platform is bring-your-own-key. Pro on Magento and on WooCommerce both call your own Anthropic or OpenAI account directly from your store. We never proxy your LLM traffic, your data goes to your provider, your provider bills you, you control the spend.
• The enterprise Hosted Engine tier can optionally manage the LLM provider key on your behalf, a separately contracted accommodation for merchants whose security team doesn't want a vendor API key sitting in their store config. Not the default on any platform.

Observability

Every AI call is logged with a consistent prefix (e.g. mba_reports_bundle_copy, mba_reports_session_intent) so production grep patterns continue working. The Jobs → AI Tasks admin grid shows status, attempt count, last error, and rendered prompt excerpt for every task. The grid is the single source of truth when debugging: if a task is stuck or failing, that's where you start.