Latest features: the AI assistant
- Version
- 3.x
- Updated
A Claude-backed advisor on the configurator and the cart — and, behind it, the record of everything it did and everything it could not. It is the largest single addition of this period, and it is deliberately not a chatbot bolted onto a product page: it is a second client of the API the page itself runs on, which is what makes it safe and what makes it useful.
What the visitor gets
A floating chat panel beside the configurator. The assistant knows the product — structure, answers, prices, descriptions, detail panes — talks in the visitor's language, and acts: makes selections, explains why an option is unavailable, runs what-ifs without committing them, scrolls the page to the question it is discussing, opens a cart configuration for editing, and adds the finished configuration to the cart.
One state, two clients — why it is safe
The assistant's tools are thin wrappers over the same controller tasks the page's own JavaScript calls, executed in the visitor's own request and session. So:
- There is one configuration state — the session's cart position.
- There is one validation path: the same ownership, product, selectable and confirmation guards that protect the page protect the assistant.
- There is one refresh mechanism — after the assistant acts, the panel re-renders from the server, so its work looks exactly like the visitor's own clicks.
The consequence is the whole security story: the assistant can never do anything the visitor could not do themselves. No admin surface, no catalog write, no other customer's data behind any tool. Even prompt injection is bounded by it — visitor text goes into messages, never the system prompt, so a hostile conversation can at worst call the visitor-scope tools.
Honesty is configured, not hoped for
The prompt guardrails encode failure modes the journal actually caught, which is worth knowing before deciding whether to switch it on:
-
Never claim an unverified change — a selection that did not stick is a failed selection whatever the engine said.
-
Live state outranks conversation history — the visitor clicks between messages.
-
Preset defaults are not the visitor's choices.
-
Pricing language follows the visitor's customer group — no figure is called net or gross unless the data's own fields say so for that figure, and a group that may not see prices is not told them.
-
The hard rule: saying "I can't" without filing a wishlist item in the same turn is forbidden.
What it could not do becomes data
The assistant files what it could not deliver, categorized: missing product information, a missing capability, an observed bug, a translation gap, UX friction. An item filed with a visitor's triggering request counts as measured demand; one filed without is a gap the assistant noticed itself, and the two are kept apart on purpose.
Three layers sit over that:
-
The demand ledger — every wish carrying a visitor's own words, aggregated live by category over a selectable window. Plain SQL, no analysis run, no tokens: it is current the moment a visitor asks for something the shop cannot do.
-
Per-conversation lessons — a review of the full transcript: what worked, what went wrong, every wishlist item judged in context, and the gaps the runtime tagging missed.
-
A durable recommendation backlog — one row per distinct problem, owned by one stakeholder, with a status lifecycle. It replaced snapshot reports because a frozen duplicate of a self-maintaining list only invites reading a stale copy. New evidence against a done recommendation flips it to regressed: the fix did not hold.
The journal
Every conversation, every turn, and every event inside a turn: the model's stated reasoning, each tool call with its payload and outcome, each attempted selection with its previous value and whether it was accepted, each page action with the reason the model gave, each refused confirmation, each error. One card per action — a tool call and what it meant are two rows by design, and the timeline pairs them back so a selection reads Battery capacity: 750 Wh (was 625 Wh) rather than three ids.
It is gated stricter than the admin area — it shows visitors' words verbatim — and pruned by a retention setting.
Getting the findings to the people who can act
The same findings, seen one audience at a time — content managers, the product owner, developers, the vendor, the store team — each with its own contact settings and a way out of the admin: an approved email, recorded with its exact text, flipping the covered items to sent.
Running it
Settings live in the store settings' AI Configurator Assistant group: API key, chat model, analysis model, persona, greeting, house rules, three separate permissions (may add to cart, may drive the page, may change the cart), a per-session rate limit, journal switches and retention. The API key never leaves the server.
Two commands support it: configbox:chatadvisor:analyze runs the lessons sweep and enforces journal
retention; configbox:chatadvisor:relay handles pending relays. Both want a cron entry.
Making a custom question type legible to it
A stock question type needs no help. A custom one — especially one whose selection is a JSON object — is a black box to a model, which guesses at the payload, gets rejected by the store, and the conversation dies. The framework lets a type state what a client would otherwise have to guess.
Two AI surfaces, two trust models
The assistant and the MCP server are both AI surfaces over the same store, and they are deliberately not the same thing: the assistant is driven by an anonymous visitor and scoped to that visitor's own cart position; the MCP server is driven by an operator's assistant with shell access and scoped to the catalog.
Next: payments & commerce · catalog operations · back to Latest features