Converse Personalization

Injects user behavior signals (clicks, cart additions, purchases) from the Pixel Worker into the converse LLM context.

How It Works

1. If pixel_id (from index settings) and userId (from request payload) are both present, converse calls PIXEL_WORKER.getPersonalizationData(pixelId, userId, sessionId) to fetch tracked events.
2. Events are grouped by type, sorted by recency, and deduplicated. Top 5 document IDs per type are kept.
3. Those documents are batch-fetched alongside any documentIds from the request, then prepended to the user message as labeled sections the LLM can reference.

Event Types

Event Type	Label in LLM Context
AddToCartEvent	"Products in the user's cart"
PurchaseEvent	"Products the user has recently purchased"
ClickEvent	"Products the user has recently viewed"

Cooldown & Caching

• 5-minute cooldown (PERSONALIZATION_COOLDOWN_MS): after a successful fetch, subsequent turns within the same conversation reuse the stored personalization context instead of calling the Pixel Worker again.
• lastPersonalizationDataAt and personalizationContext are persisted in ConversationContext (Durable Object storage) so the cooldown survives across requests.
• On fetch error, falls back to the previously stored context (if any).

Prerequisites

• pixel_id set in index settings
• userId provided in the converse request payload

If either pixel_id or userId is missing, personalization is skipped silently (logged as a warning).

Key Files

File	Purpose
src/converse/personalization.ts	fetchPersonalizationContext — calls Pixel Worker, groups events into DocGroup[]
src/converse/converse.ts	Orchestration: cooldown check, doc fetch, context injection, persistence
src/conversation-context.ts	ConversationContext type with lastPersonalizationDataAt and personalizationContext fields