Forem: Rosen Hristov

Building a Chat Assistant Module for Magento 2: Observers, Message Queues, and 10K Products

Rosen Hristov — Fri, 27 Mar 2026 14:32:49 +0000

Magento stores are large. Not WooCommerce "500 products with a few categories" large. Magento stores run 10,000+ SKUs, configurable products with dozens of variations, multiple store views for different languages, and Multi-Source Inventory across warehouses.

I built Emporiqa, a chat assistant for e-commerce stores. After shipping integrations for Drupal Commerce, WooCommerce, and Sylius, Magento was next. The catalog complexity made it the most interesting one to build.

Here's how the module works under the hood.

The Problem: Chat That Knows Nothing

Most chat solutions for Magento are JavaScript widgets that sit on the page and know nothing about your catalog. Customer asks "do you have running shoes under 80 euros in size 42?" The widget either sends them to the search page or gives a generic response.

To answer product questions, the chat assistant needs the actual catalog data: product names, descriptions, prices, stock levels, categories, images, and variation attributes. For Magento, it also needs to understand configurable product relationships and handle per-store-view translations.

Architecture: Observers → Queue → Webhooks

The module doesn't run chat processing inside Magento. That would tank admin performance. Instead, it sends product and page data to Emporiqa via webhooks, and the chat processing happens on separate infrastructure.

The flow:

Magento observer fires on catalog_product_save_after, catalog_product_delete_before, cms_page_save_after, etc.
The observer formats the product into a consolidated payload (all store view translations in one event)
The event is published to Magento's DB message queue (emporiqa.webhook.consumer)
The queue consumer sends the webhook to Emporiqa with HMAC-SHA256 signature

The flow is non-blocking: the admin saves a product, the observer runs in milliseconds, and the actual HTTP request happens asynchronously via the queue consumer.

Configurable Products: Parent/Child Consolidation

This was the tricky part. Magento's configurable products have a parent that holds the name, description, and images, plus child simple products that hold the actual SKU, price, and stock.

The module syncs both:

Parent (configurable):
  identification_number: "product-123"
  sku: "JACKET-BLUE"
  is_parent: true
  variation_attributes: {"base": {"en-us": ["Color", "Size"], "de-de": ["Farbe", "Größe"]}}
  names: {"base": {"en-us": "Trail Jacket", "de-de": "Wanderjacke"}}

Child (simple):
  identification_number: "variation-124"
  sku: "JACKET-BLUE-M"
  is_parent: false
  parent_sku: "JACKET-BLUE"
  prices: {"base": [{"currency": "EUR", "current_price": 79.99}]}
  stock_quantities: {"base": 42}

On the Emporiqa side, the assistant understands that "Trail Jacket" comes in multiple colors and sizes, with specific prices and stock per variation. A customer asking "do you have the trail jacket in medium?" gets an answer based on actual inventory.

Multi-Store-View Consolidation

Magento uses store views for languages. A product might have an English name in the default store view and a German name in the de_DE store view.

Rather than sending one webhook per store view (which would multiply requests by the number of languages), the module consolidates everything into one payload per product:

{
  "names": {
    "base": {
      "en-us": "Summer Jacket",
      "de-de": "Sommerjacke"
    }
  },
  "descriptions": {
    "base": {
      "en-us": "Lightweight jacket for warm days",
      "de-de": "Leichte Jacke für warme Tage"
    }
  }
}

The channel key "base" is the Magento website code. If you have multiple websites (e.g., base, b2b), products nest under each website's code as the channel key.

The ProductFormatter service handles this. It iterates over all enabled store views, loads the product in each store view's context, and merges the translations into one structure.

MSI: Salable Quantity vs Physical Stock

Magento's Multi-Source Inventory (MSI) tracks stock across multiple warehouses. Customers care about the salable quantity (what's actually available to sell after reservations), not the physical stock at any individual source.

The module uses MSI's GetProductSalableQtyInterface when available and falls back to StockRegistryInterface for stores not using MSI:

// Simplified: the module checks for MSI availability at runtime
try {
    $salableQty = $this->getProductSalableQty->execute($sku, $stockId);
} catch (\Exception $e) {
    // Fallback to legacy stock
    $stockItem = $this->stockRegistry->getStockItemBySku($sku);
    $salableQty = $stockItem->getQty();
}

This handles both Magento Open Source (which may not have MSI) and Adobe Commerce (which always does).

Message Queue: Why Not Direct HTTP

I could have sent webhooks directly from the observer. Drupal's integration does something similar with queue workers. But Magento's observer system runs inside the request lifecycle, and making HTTP calls during catalog_product_save_after would slow down admin operations.

Magento's DB message queue solves this. The observer publishes a message, the consumer processes it later. For large catalog imports (think: importing 5,000 products via CSV), the queue absorbs the load and the consumer works through them at its own pace.

The consumer is either started manually (bin/magento queue:consumers:start emporiqa.webhook.consumer) or runs via Magento's cron-based consumer processing.

Cart and Order Tracking

The module exposes REST endpoints at /rest/V1/emporiqa/cart/* for in-chat cart operations (add, remove, update, checkout URL). All use same-origin session cookies, no API tokens needed. The chat widget's EmporiqaCartHandler JavaScript calls these automatically.

For order tracking, a separate endpoint at /rest/V1/emporiqa/order/tracking accepts HMAC-signed requests from Emporiqa. The customer must verify their billing email before any order data is returned. Requests older than 5 minutes are rejected.

CLI Commands for Automation

Sync commands for deployment pipelines or scheduled jobs:

bin/magento emporiqa:sync:products          # Full product sync
bin/magento emporiqa:sync:pages             # Full CMS page sync
bin/magento emporiqa:sync:all               # Both
bin/magento emporiqa:test-connection         # Verify webhook connectivity
bin/magento emporiqa:sync:products --dry-run # Test without sending
bin/magento emporiqa:sync:products --batch-size=25

Each sync creates a session (sync.start → batched events → sync.complete). Items not seen during the session are marked as deleted on the Emporiqa side, so you don't need to manually delete stale products.

What Doesn't Work Well

Grouped and bundle products sync as standalone items without parent/child relationships. The module handles simple and configurable products with full parent/child consolidation. Grouped and bundle product types sync their component products individually, without the grouping structure.

The queue consumer needs babysitting. If emporiqa.webhook.consumer dies (OOM, timeout, server restart), webhook events pile up silently. Magento's cron-based consumer processing is the safer option for production, but it adds latency. There's no built-in alerting when the queue backs up.

CMS page sync is basic. Magento's CMS pages are flat content blocks. The module syncs title, content, and URL, but can't handle Page Builder layouts or widget directives. Stores using complex Page Builder pages get the raw content, which isn't always useful.

What I Learned

Three things stood out building this compared to the WooCommerce and Sylius integrations:

MSI detection is messy. You can't assume MSI is present. Magento Open Source installs may have it removed. The module needs graceful fallback at runtime, not compile time.
Configurable product observers fire for children too. When saving a configurable product, Magento also saves each child. Without deduplication, you'd send the same parent product multiple times. The queue handles this with a simple check before publishing.
Store view context switching is expensive. Loading a product in store view A, then store view B, then back to A involves Magento's store emulation. The formatter batches all store views together to minimize context switches.

Try It

The module is on the Adobe Commerce Marketplace and supports Magento 2.4.4+ (both Open Source and Adobe Commerce).

composer require emporiqa/module-chat-assistant
bin/magento module:enable Emporiqa_ChatAssistant
bin/magento setup:upgrade
bin/magento cache:flush

Start with a free sandbox store (100 products and 20 pages, no credit card). Sync some of your catalog, test with questions your customers ask, and see if the results make sense.

Full setup guide: emporiqa.com/docs/magento/. I also wrote about the full Magento integration on the Emporiqa blog.

From WooCommerce Product Save to 'Add to Cart' in a Chat Conversation

Rosen Hristov — Thu, 26 Mar 2026 14:32:58 +0000

A store owner saves a product in WooCommerce. Three seconds later, a customer on the other side of the world finds that product by typing "something warm for winter" into a chat widget, adds it to their cart, and checks out. The store owner sees the purchase attributed to the chat session on their dashboard.

That's a lot of systems talking to each other. Here's what happens at each step.

Step 1: Product Save Triggers a Webhook

The WooCommerce plugin hooks into woocommerce_update_product. When the store owner clicks "Publish" or "Update," the hook fires and queues a webhook event in memory.

The event isn't sent immediately. It goes into an in-memory queue that flushes on WordPress's shutdown action, after the HTTP response is already sent to the browser. The admin page loads at normal speed. The webhook happens a fraction of a second later.

// Simplified from the actual plugin
add_action('woocommerce_update_product', [$this, 'on_product_update']);
add_action('shutdown', [$this, 'flush_webhook_queue']);

The queue deduplicates. If a product triggers multiple hooks in one request (saving a variable product fires hooks for the parent and each variation), each product ID is queued once. The batch goes out as a single HMAC-signed POST to the webhook endpoint.

The payload is a consolidated JSON structure — one event per product with all translations nested inside:

{
  "events": [{
    "type": "product.updated",
    "data": {
      "identification_number": "product-42",
      "sku": "product-42",
      "channels": ["default"],
      "names": {"default": {"en": "Merino Wool Hiking Jacket"}},
      "descriptions": {"default": {"en": "Warm, breathable, water-resistant..."}},
      "links": {"default": {"en": "https://store.com/merino-wool-hiking-jacket"}},
      "categories": {"default": {"en": ["Outerwear > Jackets"]}},
      "brands": {"default": "TrailPeak"},
      "prices": {"default": [
        {"currency": "USD", "current_price": 149.99, "regular_price": 189.99}
      ]},
      "availability_statuses": {"default": "available"},
      "stock_quantities": {"default": 25},
      "attributes": {"default": {"en": {"Material": "Merino Wool", "Weight": "380g"}}},
      "images": {"default": ["https://store.com/jacket-front.jpg"]},
      "is_parent": false,
      "parent_sku": null,
      "variation_attributes": {}
    }
  }]
}

For multilingual stores (Polylang or WPML), the plugin sends all translations in a single event with nested language keys. A store with 3 languages and 1,000 products generates 1,000 events during a full sync, not 3,000.

Step 2: Webhook Endpoint Validates and Queues

The webhook hits the receiving endpoint. Five checks happen before anything is processed:

Rate limit (120 requests/60s per store, sliding window in Redis)
Store lookup
Subscription check
HMAC-SHA256 signature verification
Pydantic schema validation on every event

If all pass, the events go to a Celery task. The endpoint returns 202 and the store doesn't wait.

Step 3: Embedding (or Skipping It)

The Celery worker picks up the events. For each product, it computes a SHA-256 hash of the content that affects search quality (name, SKU, category, brand, description, attributes). If the hash matches what's already stored, and only the price or stock changed, the existing embedding is reused. No inference call needed.

If the content actually changed, the product goes to the inference service for a new embedding. The model (intfloat/multilingual-e5-large, 1024 dimensions) encodes the product into a vector that captures its meaning across 100+ languages.

For a typical product update where only the price changed, the embedding step is skipped entirely. During a full resync of 10,000 products where maybe 50 descriptions changed, this saves thousands of inference calls.

The product and its embedding get upserted to Qdrant, which stores both the vector and a BM25 index of the text fields.

Step 4: A Customer Types "Something Warm for Winter"

A customer on the store opens the chat widget and types a query. The message goes to a LangGraph-based pipeline.

First, a classifier looks at the message and decides which agents need to handle it. "Something warm for winter" goes to the product expert. "Something warm for winter, and what's your return policy?" goes to both the product expert and the customer support agent, running in parallel.

The product expert runs a hybrid search:

BM25 searches the text fields for exact token matches. Good for brand names, SKUs, specific attributes.

Vector search finds products that are semantically close to the query. "Something warm for winter" lands near jackets, sweaters, thermal gear, even though none of those product titles contain the words "warm" or "winter."

Both result sets get normalized to the same score range and merged. A cross-encoder reranker (ms-marco-MiniLM-L-6-v2) then compares each candidate directly against the query and re-sorts. The Merino Wool Hiking Jacket from step 1 scores high on both the vector similarity (warm + winter + outdoor) and the reranker.

The agent formats a response with product recommendations, prices, and comparison notes. If multiple agents ran in parallel, an LLM merges their responses into one coherent reply.

Step 5: Customer Adds to Cart

The customer sees the product card in the chat and clicks "Add to Cart." The widget calls window.EmporiqaCartHandler({ action: 'add', items: [...] }) on the store's frontend. This is a JavaScript function registered by the WooCommerce plugin that talks to WordPress AJAX endpoints:

emporiqa_add_to_cart    → WC()->cart->add_to_cart()
emporiqa_get_cart       → current cart state
emporiqa_update_cart    → change quantity
emporiqa_remove_from_cart → remove item
emporiqa_clear_cart     → empty cart

The plugin resolves Emporiqa's identification_number format (product-42, variation-123) back to WooCommerce integer IDs. For variable products, it resolves the correct variation based on attributes. After every operation, the WooCommerce mini-cart in the page header refreshes automatically.

The cart operations go through WooCommerce's own service layer. Store-specific rules (promotions, minimum quantities, inventory limits) still apply.

Step 6: Checkout and Conversion Attribution

The customer proceeds to checkout. The plugin hooks into woocommerce_checkout_order_processed (and the block checkout equivalent, woocommerce_store_api_checkout_order_processed) and reads the emporiqa_sid cookie (the chat session ID, set when the widget opened). It saves this as order meta.

When the order status changes to processing, completed, or on-hold (or woocommerce_payment_complete fires), the plugin sends an order.completed webhook with the session ID, line items, and totals. On the receiving end, this purchase gets attributed to the chat session that recommended the product.

One problem I had to solve: external payment gateways (PayPal, Stripe) redirect server-to-server. The browser cookie is gone by the time the order status changes. The fix was capturing the session ID during checkout (when the browser is still present) and storing it as order meta. The payment completion hook then reads it from the database, not the cookie.

// During checkout (browser present)
add_action('woocommerce_checkout_order_processed', function($order_id) {
    if (isset($_COOKIE['emporiqa_sid'])) {
        $order = wc_get_order($order_id);
        $order->update_meta_data('_emporiqa_session_id', sanitize_text_field($_COOKIE['emporiqa_sid']));
        $order->save();
    }
});

// On order status change or payment complete (server-to-server, no cookie)
// Hooks: woocommerce_order_status_processing, _completed, _on-hold, woocommerce_payment_complete
add_action('woocommerce_order_status_processing', function($order_id) {
    $order = wc_get_order($order_id);
    $session_id = $order->get_meta('_emporiqa_session_id');
    // Send order.completed webhook with session_id for attribution
});

A _emporiqa_order_tracked meta flag prevents duplicate sends. Payment gateways sometimes fire status hooks multiple times.

Step 7: The Dashboard

The store owner opens the dashboard and sees:

Chat sessions → cart adds → checkouts → purchases, with conversion rates at each step
Revenue attributed to chat conversations
Which products get recommended most, which get added to cart
Widget engagement (loads, opens, unique visitors)

This closes the loop. Product save → webhook → embedding → search → agent response → cart → purchase → attribution → dashboard.

What's Extensible

The WooCommerce plugin exposes WordPress filters for customization:

emporiqa_should_sync_product / emporiqa_should_sync_page to skip specific items
emporiqa_product_data / emporiqa_variation_data to modify payloads before sending
emporiqa_order_tracking_data to add shipment tracking numbers to order lookups
emporiqa_widget_enabled to disable the widget on specific pages

Standard WordPress patterns, no forking needed.

What I'd Do Differently

The conversion attribution relies on a cookie. If the customer clears cookies between chatting and checking out, the link breaks. There's no server-side fallback that connects the customer's identity across sessions. A logged-in user ID match would fix this, but it adds complexity for guest checkouts.

I wrote about the hybrid search pipeline, the sync architecture, and the parallel agent system separately. This post is about how they connect. The WooCommerce plugin is live on wordpress.org. I covered the full WooCommerce integration on the Emporiqa blog, and the setup docs walk through the configuration step by step. You can test the pipeline end-to-end with a free sandbox at Emporiqa.

Building a Chat Module for PrestaShop: Hooks, Deferred Sending, and Combination Sync

Rosen Hristov — Wed, 11 Mar 2026 06:44:45 +0000

I already had webhook sync modules for Drupal Commerce and Sylius. Each platform handles entity events differently. PrestaShop has its own approach: hooks, no message queue, and a combination system that doesn't map cleanly to variants.

PrestaShop's Hook System

PrestaShop uses hooks instead of event subscribers. For products, the key hooks are:

public function install()
{
    return parent::install()
        && $this->registerHook('actionProductSave')
        && $this->registerHook('actionProductDelete')
        && $this->registerHook('actionUpdateQuantity')
        && $this->registerHook('actionObjectCombinationAddAfter')
        && $this->registerHook('actionObjectCombinationUpdateAfter')
        && $this->registerHook('actionObjectCombinationDeleteAfter')
        && $this->registerHook('actionObjectCmsAddAfter')
        && $this->registerHook('actionObjectCmsUpdateAfter')
        && $this->registerHook('actionObjectCmsDeleteAfter')
        && $this->registerHook('displayHeader')
        && $this->registerHook('actionValidateOrder')
        && $this->registerHook('actionOrderStatusPostUpdate');
}

The last three hooks handle widget embedding and conversion tracking. displayHeader auto-embeds the chat widget script on every front-office page. actionValidateOrder and actionOrderStatusPostUpdate handle the conversion pipeline (more on that below).

Products and CMS pages use different hook naming patterns. Products get actionProductSave (which fires on both create and update). CMS pages use the actionObject*After pattern with separate hooks for add, update, and delete. Combinations also use the actionObject*After pattern.

This is different from Drupal's OOP hook pattern (commerceProductInsert / commerceProductUpdate / commerceProductDelete), and from Sylius's sylius.product.post_create resource events. In PrestaShop, you register hooks in install() and implement them as class methods.

The Deferred Sending Problem

PrestaShop doesn't have a built-in message queue. Magento has MessageQueuePublisher. Shopware has Symfony Messenger. Sylius has kernel.terminate. PrestaShop has none of these.

Sending webhooks synchronously inside a hook would slow down every product save in the admin. Saving a product with 10 combinations might trigger 11 hook calls. If each one made an HTTP request, the admin would freeze.

The solution: deferred sending with register_shutdown_function.

class EmporiqaWebhookClient
{
    private array $pendingEvents = [];
    private bool $shutdownRegistered = false;

    public function queueEvent(string $type, array $data): void
    {
        $this->pendingEvents[] = ['type' => $type, 'data' => $data];

        if (!$this->shutdownRegistered) {
            register_shutdown_function([$this, 'flushPendingEvents']);
            $this->shutdownRegistered = true;
        }
    }

    public function flushPendingEvents(): void
    {
        if (function_exists('fastcgi_finish_request')) {
            fastcgi_finish_request();
        }

        // Now send all queued events
        foreach ($this->pendingEvents as $event) {
            $this->sendEvent($event);
        }
    }
}

register_shutdown_function runs after PHP finishes the main request. fastcgi_finish_request() (available on PHP-FPM) sends the response to the browser immediately, so the admin page loads while webhooks fire in the background.

This is the same concept as Sylius's kernel.terminate, but adapted for PrestaShop's architecture. Both achieve the same goal: don't make the user wait for HTTP requests they don't need to see.

Comparison: How Each Platform Handles Async Delivery

Platform	Mechanism	When it runs
Magento	DB message queue + consumer	Background worker process
Shopware	Symfony Messenger + async transport	Background worker process
Sylius	`kernel.terminate` event	After response sent, same process
PrestaShop	`register_shutdown_function`	After response sent, same process
Drupal	Queue API + cron worker	Background cron process

Sylius and PrestaShop both run in the same PHP process after the response. Magento, Shopware, and Drupal use separate worker processes. The tradeoff: same-process is simpler (no worker to manage) but ties webhook delivery to the web request lifecycle.

Deduplication

Saving a product with combinations can trigger actionProductSave multiple times in one request. Without dedup, you'd send the same product data three times.

private array $queuedProductIds = [];
private array $queuedPageIds = [];

public function hookActionProductSave($params)
{
    $productId = (int) $params['id_product'];

    if (isset($this->queuedProductIds[$productId])) {
        return;
    }

    $this->queuedProductIds[$productId] = true;
    $this->webhookService->queueEvent('product.updated', $this->formatProduct($productId));
}

Simple array tracking per request. Product IDs and page IDs are tracked separately. This prevents the deferred queue from containing duplicate events for the same entity.

Combination Handling

PrestaShop's combination system is the trickiest part. A product can have combinations (Color: Red + Size: M, Color: Blue + Size: L, etc.). These are separate database records linked to the parent product.

The external service stores products with all variations in one record. So combination changes need to trigger a parent product re-sync:

public function hookActionObjectCombinationUpdateAfter($params)
{
    $combination = $params['object'];
    $productId = (int) $combination->id_product;

    // Re-sync the parent product (which includes all combinations)
    $this->syncProduct($productId);
}

public function hookActionObjectCombinationDeleteAfter($params)
{
    $combination = $params['object'];
    $productId = (int) $combination->id_product;

    // Send delete event for the specific variation
    $this->webhookService->queueEvent('product.deleted', [
        'identification_number' => 'variation-' . $combination->id,
    ]);

    // Re-sync the parent so it reflects the remaining combinations
    $this->syncProduct($productId);
}

Deleting a combination requires two actions: a delete event for the variation itself, and a re-sync of the parent product so the external service knows which combinations remain. This is different from Magento's configurable products or Sylius's product variants, but the end result is the same.

Customization Hooks

PrestaShop doesn't have Symfony's service decoration or Magento's DI preferences. Instead, I used PrestaShop's own hook system for customization:

public function hookActionEmporiqaFormatProduct($params)
{
    // Other modules can modify product data before it's sent
    // $params['data'] is passed by reference (also receives 'product' and 'event_type')
}

public function hookActionEmporiqaShouldSyncProduct($params)
{
    // Other modules can prevent a product from syncing
    // Set $params['should_sync'] = false to skip
}

Seven hooks total: actionEmporiqaShouldSyncProduct, actionEmporiqaShouldSyncPage, actionEmporiqaFormatProduct, actionEmporiqaFormatPage, actionEmporiqaFormatOrder, actionEmporiqaOrderTracking, actionEmporiqaWidgetParams.

This is PrestaShop's equivalent of Drupal's alter hooks, Sylius's service decoration, and Magento's DI preferences. Each platform uses its own extensibility mechanism. The goal is the same: let other code modify behavior without editing the module.

Admin Sync UI (No CLI)

PrestaShop doesn't have a standard CLI framework like Drush (Drupal), WP-CLI (WordPress), or bin/console (Symfony/Shopware). Magento has bin/magento. PrestaShop has nothing equivalent.

The initial sync uses an AJAX-powered admin UI instead:

Click "Start Sync"
JavaScript calls the module's admin controller with action=init
Controller returns total product/page count
JavaScript calls action=batch repeatedly with offset/limit
Progress bar updates after each batch
Final call to action=complete triggers reconciliation

This approach works well for PrestaShop's audience. Store owners are more likely to click a button in the admin than SSH into a server and run a CLI command.

Cart Operations

PrestaShop doesn't have a REST API like Magento's rest/V1/ or WooCommerce's /wp-json/wc/. For cart operations (add to cart, update quantity, remove, checkout), I used a front controller:

// modules/emporiqa/controllers/front/cartapi.php
class EmporiqaCartapiModuleFrontController extends ModuleFrontController
{
    public function postProcess()
    {
        $action = Tools::getValue('action');

        match ($action) {
            'add' => $this->addToCart(),
            'remove' => $this->removeFromCart(),
            'update' => $this->updateQuantity(),
            'clear' => $this->clearCart(),
            'get' => $this->getCart(),
            'checkout-url' => $this->getCheckoutUrl(),
            default => $this->respondError('Unknown action'),
        };
    }
}

The chat widget's JavaScript calls these endpoints. Front controllers are PrestaShop's standard way to expose custom URLs from a module.

Conversion Tracking

The module tracks whether a chat session led to a purchase. When a customer places an order, actionValidateOrder fires and the module captures the chat session cookie from the request, storing the order-to-session mapping in a custom database table. Later, when the order reaches a completed status (payment accepted, delivered, etc.), actionOrderStatusPostUpdate fires and sends an order.completed webhook with the session ID, order total, and currency. This lets the external service attribute revenue to specific chat conversations without polling the store for order data.

What Doesn't Work Well

No background worker: The shutdown function approach works, but it means webhook delivery depends on the PHP process completing. If PHP times out or crashes, queued events are lost. Platforms with proper message queues (Magento, Shopware) handle this better.

Hook naming inconsistency: Products use actionProductSave while CMS pages use actionObjectCmsUpdateAfter. Combinations use actionObjectCombinationUpdateAfter. Three different patterns for the same concept. You just have to know which pattern each entity uses.

No built-in REST API: Every AJAX endpoint requires a front controller. Magento's webapi.xml and Shopware's route annotations are much cleaner.

Key Takeaway

Every platform has its own way of handling entity events, async processing, and extensibility. PrestaShop's approach (hooks + shutdown function + front controllers) is older and less structured than Symfony-based or Magento-based alternatives, but it works. The module syncs products and pages reliably, handles combinations correctly, and doesn't slow down the admin.

The full module is available for PrestaShop 8.0+ / 9.0+ with PHP 7.4+ on the PrestaShop Addons Marketplace, or free when you create an Emporiqa account. Documentation. I wrote more about the full PrestaShop integration story on the Emporiqa blog.

Your Drupal Commerce Store Serves 6 Languages. Your Chat Handles One.

Rosen Hristov — Wed, 04 Mar 2026 12:46:54 +0000

I already had a webhook sync module for Drupal Commerce. Products synced, the chat widget worked, customers could search and get answers. Then a store in Norway asked me why the assistant was answering in English when their site was in Norwegian.

The module was syncing products. But only the default language. A store with translations in Norwegian, Swedish, Danish, and Finnish was sending English-only product data to the chat service. The assistant searched English descriptions and responded in English regardless of the store view. Their entire investment in translations was invisible to the chat.

I spent two weeks fixing this. Here's what "multilingual chat" means, technically.

How Translations Work in Drupal Commerce

Drupal Commerce uses the Content Translation module. A product entity has a canonical version (usually English) with translation sets for each enabled language. Each translation carries its own title, description, meta description, and any translatable custom fields.

Product: Winter Jacket (node/42)
├── en: "Winter Jacket" / "Waterproof, breathable..."
├── no: "Vinterjakke" / "Vanntett, pustende..."
├── sv: "Vinterjacka" / "Vattentät, andningsbar..."
└── da: "Vinterjakke" / "Vandtæt, åndbar..."

Drupal stores these as separate field_data rows keyed by language code. When you load a product with a specific language context, you get that language's field values with automatic fallback to the default if a translation is missing.

For Commerce stores with product variations, the numbers multiply. A jacket with 3 colors and 4 sizes means 12 variations. Each variation can have its own translated title and attributes. Across 4 languages, that's 48 translation sets for one product. A store with 5,000 products in 4 languages can easily have 100,000+ translated field entries.

Three Layers of "Multilingual"

When a vendor says "multilingual support," ask which layer:

Layer 1: Widget UI. The chat interface (buttons, placeholders, system messages) displays in the visitor's language. This is the easy part. Load a translated string file, switch based on Drupal's current language.

Layer 2: Search index. When a Norwegian customer searches for "vinterjakke," the search needs to hit Norwegian product data. If the index only contains English descriptions, the search either returns nothing (the word "vinterjakke" doesn't appear in English text) or returns irrelevant results from fuzzy matching.

Layer 3: Response language. The LLM composes its answer in Norwegian, using Norwegian product names and descriptions as source material. If it pulls from the English index and translates on the fly, the product names won't match what the customer sees on the store.

Most chat tools get Layer 1 right but stop there, leaving Layers 2 and 3 unaddressed. They translate the UI, search a single English index, and hope the LLM's output translation is good enough.

How the Module Handles This

The first version of my Drupal module sent one webhook per product containing only the default language fields. The fix was to iterate over all enabled languages, load each translation, and nest them in a single payload:

{
  "type": "product.updated",
  "data": {
    "identification_number": "PROD-42",
    "sku": "WJ-001",
    "channels": ["1"],
    "names": {
      "1": { "en": "Winter Jacket", "no": "Vinterjakke", "sv": "Vinterjacka", "da": "Vinterjakke" }
    },
    "descriptions": {
      "1": { "en": "Waterproof, breathable...", "no": "Vanntett, pustende...", "sv": "Vattentät, andningsbar...", "da": "Vandtæt, åndbar..." }
    },
    "prices": {
      "1": [{ "currency": "EUR", "current_price": 89.99, "regular_price": 119.99 }]
    },
    "availability_statuses": { "1": "available" },
    "stock_quantities": { "1": 25 }
  }
}

The channel key "1" is the Drupal Commerce store ID. Stores with multiple Commerce stores would use each store's ID as the channel key, each with their own prices and availability. All translatable fields (names, descriptions, links, attributes) nest languages inside the channel key.

One HTTP request per product instead of four. On the receiving side, Emporiqa builds a separate search index for each language. Norwegian product descriptions go into the Norwegian index, Swedish into the Swedish index.

The module reads enabled languages from Drupal's LanguageManagerInterface and checks which translations exist for each product. Missing translations fall back to the default language rather than sending empty fields.

The widget embed tag carries the language:

<script async
  src="https://emporiqa.com/chat/embed/?store_id=STORE_ID&language=no">
</script>

In the Drupal module, the language code comes from the current language context via \Drupal::languageManager()->getCurrentLanguage(). A visitor on the Norwegian store view gets language=no, the widget loads Norwegian UI text, searches the Norwegian index, and the LLM responds in Norwegian.

Cross-Language Search

A Bulgarian tourist visits a Norwegian store and types "зимно яке" (Bulgarian for winter jacket). The products are in Norwegian.

Keyword matching fails completely. "зимно яке" shares zero characters with "Vinterjakke." But multilingual embedding models map both phrases to nearby points in vector space because they mean the same thing. The vector search returns the Norwegian winter jacket without any explicit translation step.

I use multilingual embeddings that cover 65+ languages. The same model encodes both the Norwegian product descriptions and the Bulgarian query into vectors in a shared space. Semantic similarity works across language boundaries.

A German store serving Austria and Switzerland will have customers who also speak Turkish, Croatian, Italian, or Serbian. The chat handles all of them without the store needing translations in each of those languages.

What Doesn't Work Well

Partial translations are the biggest issue. A product with English and Norwegian translations but no Swedish version means Swedish customers see the English fallback. The assistant doesn't warn them it's showing content in a different language. It returns what it found.

Missing field translations create a subtler problem. Some stores translate product titles but not descriptions. The search finds the product by its Norwegian title, but the description comes back in English. The response mixes languages. Confusing for the customer.

First-message language mismatch. The widget language is set by the embed tag based on Drupal's current store view. If an English-speaking tourist on a Norwegian site types in English, the system detects the switch after processing the first message. That first response may come back in Norwegian before it adapts.

CMS page gaps. If your return policy only exists in English, a French customer asking about returns gets English text. Technically accurate, but not a great experience. The fix is simple (translate your key policy pages), but many stores skip this for low-traffic languages.

The Practical Takeaway

Multilingual chat is only as good as your translation data. Full translations across all products and pages give the best results. Partial translations work but produce mixed-language responses. No translations mean everyone gets the default language regardless of the store view.

If you're running a multilingual Drupal Commerce store, the question worth asking about any chat tool is: "does it search the right language index and respond in the right language with the right product names?"

The Emporiqa module on drupal.org handles translation sync, language detection, and widget embedding for Drupal 10+. I go deeper into how the multilingual pipeline works on the Emporiqa blog. The full setup guide is at emporiqa.com/docs/drupal/. You can test multilingual search with a free sandbox (100 products, no credit card).

Building a Sylius Plugin with Webhook Sync, Service Decoration, and kernel.terminate

Rosen Hristov — Fri, 27 Feb 2026 09:38:08 +0000

I already had a webhook sync module for Drupal Commerce. Drupal uses entity hooks, queue workers, and alter hooks. For Sylius, none of that applies.

Sylius sits on Symfony. That means event subscribers, service decoration, console commands, and kernel.terminate. The plugin needed to feel like a Symfony bundle, not a ported Drupal module.

Two Event Systems for Two Entity Types

Products in Sylius are proper Sylius resources. They fire resource events: sylius.product.post_create, sylius.product.post_update, sylius.product_variant.post_create, etc. An event subscriber catches these:

class ProductEventSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            'sylius.product.post_create' => 'onProductCreate',
            'sylius.product.post_update' => 'onProductUpdate',
            'sylius.product.pre_delete'  => 'onProductDelete',
            'sylius.product_variant.post_create' => 'onVariantCreate',
            'sylius.product_variant.post_update' => 'onVariantUpdate',
            'sylius.product_variant.pre_delete'  => 'onVariantDelete',
        ];
    }
}

When a variant changes, the subscriber re-syncs the entire parent product. The external service stores products with all their variations in one record, so a variant update means the whole product needs refreshing.

Pages work differently. Sylius has no built-in Page entity. Stores use BitBag CMS, custom entities, or nothing. These aren't Sylius resources, so they don't fire resource events. I used Doctrine lifecycle listeners instead:

#[AsDoctrineListener(event: Events::postPersist)]
#[AsDoctrineListener(event: Events::postUpdate)]
#[AsDoctrineListener(event: Events::preRemove)]
class PageDoctrineListener
{
    public function postPersist(PostPersistEventArgs $args): void
    {
        $entity = $args->getObject();
        if ($this->isTrackedPage($entity)) {
            $this->queue('page.created', $entity);
        }
    }
}

The listener only fires if the entity implements PageInterface and its class is listed in the bundle config:

emporiqa:
  page_entity_classes:
    - App\Entity\Page

PageInterface is minimal — getId() and getTranslations(). Existing page entities from any CMS plugin can implement it without changing their schema.

This was a design tradeoff. I could have required a specific page entity structure, which would make the plugin easier to build but harder to adopt. Or I could make page sync entirely optional and interface-based, which is what I did. Most stores don't have pages at all, and the ones that do all structure them differently.

Deferred Sending via kernel.terminate

Sending HTTP requests during an admin save action is slow. The Drupal module uses queue workers. For Symfony, I used kernel.terminate.

Events aren't sent immediately when they fire. They go into a WebhookEventQueue — an in-request buffer:

class WebhookEventQueue implements EventSubscriberInterface
{
    private array $queue = [];

    public function queue(string $type, array $data): void
    {
        $key = $data['identification_number'];

        // Delete always wins
        if (str_ends_with($type, '.deleted')) {
            $this->queue[$key] = ['type' => $type, 'data' => $data];
            return;
        }

        // Don't overwrite a delete with an update
        if (isset($this->queue[$key]) && str_ends_with($this->queue[$key]['type'], '.deleted')) {
            return;
        }

        $this->queue[$key] = ['type' => $type, 'data' => $data];
    }
}

The queue deduplicates by identification_number. If a product is saved twice in one request (bulk operations), only the last event goes out. All translations are consolidated into a single event per product. Delete always wins over create/update — if something is deleted, there's no point sending the create that preceded it.

On kernel.terminate, after the HTTP response is already sent to the browser, the queue flushes and sends everything in one batch. The admin UI stays fast. The webhook happens a few hundred milliseconds later.

This doesn't work for CLI commands though — there's no HTTP kernel in a console context. The sync commands send batches directly via WebhookSender.

Service Decoration for Customization

Where Drupal uses alter hooks, Symfony has service decoration.

The plugin formats products into webhook payloads via ProductFormatter. If a store has custom attributes (warranty, vehicle compatibility, material composition), the store developer decorates the formatter:

class CustomProductFormatter implements ProductFormatterInterface
{
    public function __construct(
        private ProductFormatterInterface $inner,
    ) {}

    public function format(ProductInterface $product): array
    {
        $events = $this->inner->format($product);

        foreach ($events as &$event) {
            if ($product->hasAttribute('warranty_years')) {
                // Attributes use {channel: {language: {name: value}}} nesting
                foreach ($event['data']['attributes'] as $channel => &$languages) {
                    foreach ($languages as $lang => &$attrs) {
                        $attrs['warranty'] = $product
                            ->getAttributeByCodeAndLocale('warranty_years', $lang)
                            ?->getValue() . ' years';
                    }
                }
            }
        }

        return $events;
    }
}

Register it in services.yaml with a #[AsDecorator] attribute or the standard Symfony decorates key. The original formatter becomes $inner, and your code wraps it.

For cases where you need to skip sync for specific entities or modify the payload batch before it's sent, the plugin dispatches Symfony events:

emporiqa.pre_sync (cancellable, fired before any entity syncs)
emporiqa.post_format (fired after formatting, you can modify the payload before queuing)
emporiqa.pre_webhook_send (fired before the HTTP batch, you can modify or filter events)
emporiqa.order_tracking (fired after order lookup, you can modify the response)
emporiqa.cart_operation (fired before a cart operation, cancellable)

Service decoration for structural changes, event listeners for conditional logic — both standard Symfony.

Cart Operations via Sylius's Own Services

The plugin provides cart API endpoints that the chat widget calls. The implementation uses Sylius's native services:

CartContextInterface to get the current cart
OrderModifierInterface to add items
OrderItemQuantityModifierInterface to update quantities

GET  /emporiqa/api/cart           → current cart state
POST /emporiqa/api/cart/add       → add item by variation_id
POST /emporiqa/api/cart/update    → update quantity
POST /emporiqa/api/cart/remove    → remove item
POST /emporiqa/api/cart/clear     → empty cart
GET  /emporiqa/api/cart/checkout-url → redirect URL
GET  /emporiqa/api/user-token        → signed user token

No custom cart logic. The plugin delegates to whatever Sylius is already doing for cart management. If the store has custom cart rules (promotions, inventory checks), they still apply because the plugin goes through Sylius's own service layer.

Conversion Tracking

An event subscriber listens for Symfony Workflow events on order completion:

public static function getSubscribedEvents(): array
{
    return [
        'workflow.sylius_order_checkout.completed.complete' => 'onOrderComplete',
    ];
}

When a checkout completes, the subscriber reads an emporiqa_sid cookie (the chat session ID, set by the widget JavaScript), assembles an order.completed webhook payload with line items, totals, and currency, and queues it via WebhookEventQueue.

On the receiving end, this links the chat session to the purchase. The dashboard shows chat-attributed revenue.

The subscriber works with both Sylius 2.x (Symfony Workflow events) and 1.x (Winzou State Machine callbacks), so conversion tracking is available regardless of which version the store runs.

What Doesn't Work Well

Page sync is opt-in and requires effort. Since Sylius has no standard Page entity, every store needs to implement PageInterface on whatever they're using for content. Some stores skip page sync entirely because the effort isn't worth it for a handful of policy pages. I provide samples in the README, but it's still manual work.

PageUrlResolver is a stub. The plugin can't know how a store routes to its page entities. The default resolver returns empty strings. Stores need to override it with a service that knows their routing. This is the most common "it doesn't work" issue I hear about.

CLI sync doesn't use kernel.terminate. Console commands send batches directly, which means the deduplication logic in WebhookEventQueue doesn't apply. The sync commands handle batching themselves with a different code path. Two sending mechanisms for the same data, which isn't ideal.

The plugin is on Packagist: emporiqa/sylius-plugin. Sylius ^1.12 or ^2.0, PHP 8.1+. The setup docs walk through installation and configuration. I also wrote about the full integration story on the Emporiqa blog. You can see the product sync and cart working with a free sandbox at Emporiqa.

Your Chatbot Recommends Products You Don't Sell

Rosen Hristov — Thu, 26 Feb 2026 12:47:47 +0000

I was testing my product agent on a demo store that sells electronics. I typed "do you have leather jackets?" The agent searched, got zero results, and instead of admitting the store doesn't carry jackets, it generated product recommendations from its training data. Product names, prices, descriptions that weren't in the store.

This is what happens when a ReAct agent with a search tool has no concept of what the store actually sells. It searches, gets nothing useful, and fills the gap with whatever the LLM thinks a helpful response should contain.

I tried prompt engineering first. "Only recommend products from search results." "Never invent products." "If search returns no results, say so." It helped with the simple cases but broke down on subtler ones. The agent would find vaguely related products and stretch the recommendation to fit the query.

Prompt engineering wasn't going to fix this. The agent needed a model of the store's inventory.

The Agent Has No Inventory Model

A typical product search agent works like this:

Customer asks a question
Agent decides to search
Search returns results (or doesn't)
Agent generates a response

The agent knows nothing about the store until after it searches. If the customer asks about a category that doesn't exist, the agent can't know that in advance. It searches, gets poor results, and has to improvise a response. That's where hallucinations come from.

Check the Catalog First

I added a preprocessing step between the customer message and the agent. Before the agent runs, the preprocessor loads the store's actual catalog metadata and analyzes the query against it.

class StoreContext(BaseModel):
    categories: list[str]            # ["Smartphones", "Laptops", "Headphones"]
    brands: list[str]                # ["Apple", "Samsung", "Sony"]
    total_products: int              # 847
    category_counts: dict[str, int]  # {"Smartphones": 234, "Laptops": 156, ...}

The context comes from the database, cached per store. The preprocessor gives this to a fast LLM along with the customer's query:

Store categories (product count): Smartphones: 234, Laptops: 156, Headphones: 89, ...
Store brands: Apple, Samsung, Sony, ...

Query: "do you have leather jackets?"
Context: First message

The LLM returns a structured response with one of four actions:

no_match: Store doesn't carry this. Respond directly.
show_products: Small category (10 or fewer products). Fetch and display them.
qualify: Ambiguous query. Ask a clarifying question.
search: Pass to the full agent with pre-extracted filters.

For "leather jackets" on an electronics store, the preprocessor returns no_match with a response mentioning what the store does carry. The agent never runs, and there's nothing to hallucinate.

The Four Paths

no_match catches impossible queries early. "Do you have ski equipment?" on a bookstore. The preprocessor sees the categories (Fiction, Non-fiction, Children's, Academic), confirms ski equipment isn't among them, and says so. Saves an agent invocation and prevents the agent from trying to stretch book recommendations into ski gear.

show_products handles small categories directly. "What teas do you have?" on a store with 6 teas. Instead of running the full search pipeline (embed the query, retrieve candidates, rerank, invoke the agent), the preprocessor fetches all 6 products and presents them. Less latency, and the customer sees everything without the agent deciding what to show.

qualify fires when the query is genuinely ambiguous. "I need a gift" could match every category. The preprocessor asks what kind of gift, mentioning the actual categories available. But only when the ambiguity is real. "I need headphones" goes straight to search even on a store with 200 headphones, because the intent is clear.

search is the default. The query goes to the full agent with hybrid search, reranking, and tool use. But the preprocessor passes along structured filters it already extracted:

class ExtractedFilters(BaseModel):
    categories: list[str] | None     # Matched to real store categories
    brand: list[str] | None
    price_min: float | None
    price_max: float | None
    attributes: list[AttributeFilter]  # [{"name": "color", "value": "red"}]

"Wireless Sony headphones under $200" becomes:

{
    "categories": ["Headphones"],
    "brand": ["Sony"],
    "price_max": 200,
    "attributes": [{"name": "connectivity", "value": "wireless"}]
}

The categories and brands are matched against real store data. The preprocessor won't extract "Nike" as a brand if the store doesn't carry Nike. The agent starts with filters grounded in real inventory.

The Tradeoff: An Extra LLM Call

Every product query now makes at least two LLM calls: the preprocessor, then the agent. The preprocessor uses a fast, cheap model (GPT-4o-mini or DeepSeek). It costs fractions of a cent and adds under a second of latency.

I considered doing this without an LLM. Pattern matching on category names, fuzzy string matching, keyword overlap. But the mapping requires understanding that "phones" means Smartphones, "TVs" means Televisions, "something for the kitchen" means Kitchen Appliances. String comparison can't do this reliably.

The structured output (QueryAnalysis as a Pydantic model with response_model) means the LLM returns typed data, not free text. Four possible actions, each with specific fields. No parsing ambiguity.

What Still Goes Wrong

The preprocessor depends on the LLM's judgment for category matching. "Winter coats" on a store with an "Outerwear" category requires the LLM to know that winter coats are a subset of outerwear. It usually gets this right. Not always.

Conversation context can get lost. If the customer asked about headphones three messages ago and now says "what about the wireless ones?" the preprocessor needs the conversation summary to understand this is still about headphones. The summary is passed in, but summarization sometimes drops details.

The show_products path doesn't handle variation-heavy categories well. A category with 8 products that are all color variants of the same item shows 8 near-identical entries. I haven't solved this.

And the preprocessor can be too aggressive with no_match. If a store sells "Outdoor Gear" and the customer asks for "camping equipment," the LLM might not connect the two. The fallback is to route to search when confidence is low, but some edge cases still produce unhelpful "we don't carry that" responses for products the store actually has under a different name.

The Result

Before the preprocessor: the agent searched for everything, hallucinated on misses, and had no sense of what the store carried.

After: impossible queries get a direct answer immediately. Small categories get shown directly. Ambiguous queries get a focused question. The agent only runs when there's something worth searching for, and it starts with pre-extracted filters instead of raw text.

The preprocessor itself is about 80 lines of logic plus another 80 for the Pydantic models. The prompt template is 50 lines. It added about 200 lines of code to the pipeline and cut hallucination on out-of-stock and wrong-category queries significantly.

I wrote about the hybrid search pipeline and the parallel agent system in separate posts. The preprocessor sits before both, deciding what kind of handling each query needs. The code is part of Emporiqa, a chat assistant for e-commerce stores. Free sandbox if you want to try it.

Why I Split One LangGraph Agent into Four Running in Parallel

Rosen Hristov — Tue, 24 Feb 2026 13:31:15 +0000

My first version was a single agent with 12 tools. Product search, page lookup, order tracking, general chitchat. One system prompt, one LLM call, one response.

It worked fine for simple questions. "Show me running shoes" returned running shoes. "What's your return policy?" returned the return policy.

Then someone asked: "Do you have the Nike Air Max in size 42, and what's your return policy for shoes?"

The agent searched for Nike Air Max, found it, answered the sizing question, and completely forgot about the return policy. It had already used up its reasoning budget on the product search. The return policy part of the question just vanished.

That is when I started breaking it into specialized agents.

The Architecture

I built a chat assistant for e-commerce stores. It needs to handle product discovery (search, filter, compare), customer support (store policies, shipping info), and order tracking (status lookup via the store's API). These are fundamentally different tasks. A product search agent needs vector search tools and product database access. A customer support agent needs policy documents. An order tracking agent needs an external API client with HMAC signing.

Here is the graph:

START -> summarize -> classify -> [parallel agents] -> merge -> END

The classify node looks at the customer's message and decides which agents need to run. If someone asks "Show me running shoes and what's your return policy?", the classifier produces two assignments:

[
    AgentAssignment(agent="product_expert", sub_query="Show me running shoes"),
    AgentAssignment(agent="customer_support", sub_query="What is your return policy?"),
]

Each agent gets its own sub-query. They run in parallel. Then a merge node combines the responses.

Here's what the implementation actually looks like.

The Send API Is the Non-Obvious Part

Most LangGraph tutorials show conditional edges: "if category is X, go to node A; if Y, go to node B." That is fine for single-agent routing. But when you need two agents to run in parallel on the same message, you need the Send API.

from langgraph.types import Send

def _route_to_agents(state: GraphState) -> list[Send] | str:
    assignments = state.get("classification_assignments", [])

    agent_to_node = {
        "product_expert": "product_expert",
        "customer_support": "customer_support",
        "order_tracking": "order_tracking",
        "general": "general",
    }

    sends = []
    for assignment in assignments:
        agent = assignment.get("agent")
        node = agent_to_node.get(agent)
        if node:
            sub_query = assignment.get("sub_query")
            sends.append(Send(node, {**state, "current_sub_query": sub_query}))

    if sends:
        return sends

    # Fallback: if no assignments, send to general
    messages = state.get("messages", [])
    fallback_query = messages[-1].content if messages else ""
    return [Send("general", {**state, "current_sub_query": fallback_query})]

Each Send creates a branch with its own copy of the state, with current_sub_query set to that agent's specific sub-question. The agents run in parallel and their results converge at the merge node.

The part that tripped me up: when parallel branches write to the same state key, you need a reducer. Without one, the last branch to finish just overwrites the others.

from typing import Annotated

def _merge_agent_results(left: dict | None, right: dict | None) -> dict:
    if right is not None and not right:
        return {}  # Empty dict resets (used between turns)
    if left is None:
        return right or {}
    if right is None:
        return left
    return {**left, **right}

class GraphState(MessagesState):
    agent_results: Annotated[dict | None, _merge_agent_results] = None

The Annotated type with the reducer function tells LangGraph how to merge agent_results when multiple branches update it. Each agent writes its result under its own key (like {"product_expert": {...}}), and the reducer merges them into one dict.

One subtle detail: that empty-dict check at the top of the reducer. The classify node resets agent_results to {} at the start of each turn. Without this, results from the previous turn would bleed into the current one. I found this bug after a customer got a response that mixed product recommendations from their first question with policy information from their second.

State Management with contextvars

LangGraph passes state between nodes as function arguments. But tools, services, and utility functions that run deep in the call stack also need access to request-scoped data. I needed three distinct scopes:

ExecutionContext (immutable per request): store ID, language, thread ID. Set once, never changes.

@dataclass(frozen=True)
class ExecutionContext:
    store_id: int
    language: str
    thread_id: str | None = None

GraphState (mutable per turn): messages, conversation summary, classification results, agent outputs.

ServiceCache (request-scoped singletons): LLM instances, search services, database lookups that should only happen once per request.

class ServiceCache:
    @classmethod
    def get_llm(cls, model_type="normal", temperature=None):
        ctx = ExecutionContext.get()
        cache_key = f"llm:{ctx.store_id}:{model_type}:{temperature}"
        cache = cls._get_cache()
        if cache_key not in cache:
            cache[cache_key] = LLMHelperService.for_context(
                model_type=model_type, temperature=temperature,
            )
        return cache[cache_key]

All three live in contextvars.ContextVar, which gives thread safety without passing objects through every function signature. A tool 5 layers deep in the call stack can call ExecutionContext.get_store_id() and get the right store.

The alternative is threading the store ID through every function call. I tried that first. It works until you have 15 tools across 3 agents, each calling 2-3 services. Then your function signatures turn into def search_products(query, store_id, language, ...) everywhere.

Merging N Agent Responses

Tutorials show merging two things. Production needs to handle 1, 2, 3, or 4 agents responding simultaneously.

For a single agent, there is no merge. Just pass through:

if len(agents) == 1:
    first_result = agent_results[agents[0]]
    response_text = first_result.get("response", "")

For multiple agents, an LLM merges the responses into a single coherent reply. The merge prompt gets all agent responses formatted as numbered sections, plus the original query and the customer's language.

One design decision I had to make: confidence aggregation. When three agents respond and one has low confidence, should that trigger a human handoff? My formula weights the minimum confidence at 70% and the average at 30%:

def _get_confidence(agent_results: dict) -> float:
    confidences = [r.get("confidence", 0.5) for r in agent_results.values()]
    if len(confidences) == 1:
        return confidences[0]
    return 0.7 * min(confidences) + 0.3 * sum(confidences) / len(confidences)

This way, one confused agent can flag the whole response for review, but two confident agents can offset a slightly uncertain third. I tuned these weights manually over a few hundred test conversations.

What Goes Wrong

Misclassification. The classifier sometimes sends a product question to the general agent, or splits a single question into two agents when one would do. I use the "fast" LLM for classification (cheaper, faster) and the "normal" model for the agents themselves. The tradeoff is that the fast model occasionally gets the routing wrong. Structured output with Pydantic helps (the classifier returns a typed list[AgentAssignment], not free text), but it is not perfect.

Feature availability at runtime. Order tracking requires the store to have an API endpoint configured. If the classifier routes to order tracking but the store has not set one up, I remap to customer support at dispatch time:

if agent == "order_tracking" and not order_tracking_available:
    agent = "customer_support"

This means the customer support agent gets a question like "Where is my order #12345?" and has to explain that order tracking is not available, rather than just failing silently.

The first-turn optimization. Generating a conversation summary on the very first message is wasteful. There is nothing to summarize. So the summarize node checks:

def _is_first_turn(messages, previous_summary):
    return len(messages) == 1 and not previous_summary

On first turn, it just truncates the message to 200 characters as the "summary." The LLM call only happens from the second turn onward, when there is actual conversation history to compress.

Limitations

This architecture adds latency. Classify, dispatch, execute, merge: that is 3-4 LLM calls minimum for a multi-agent response, versus 1 for a single agent. For simple questions ("What are your store hours?"), the overhead of classification and merging is unnecessary. I have not found a clean way to short-circuit this without adding yet another classification step.

The connection pool for the PostgreSQL checkpointer needs careful sizing. I run 7 Gunicorn workers with a pool of max 5 connections each. That is 35 potential connections just for checkpointing, on top of Django's own database connections. If your database has a low max_connections, this will bite you.

The confidence aggregation formula is hand-tuned. It works for my use case but I have no proof it generalizes. If you have a better approach for aggregating confidence across parallel agents, I would like to hear it.

The product expert agent uses a hybrid search pipeline (vector + BM25 with cross-encoder reranking). I wrote more about how the agent architecture works in practice on the Emporiqa blog. You can see all four agents working on a real catalog with a free sandbox at Emporiqa.

Hybrid Search for E-commerce: When Keywords Alone Fail

Rosen Hristov — Tue, 24 Feb 2026 08:17:24 +0000

I wrote about abandoning vector-only search after SKU lookups returned random products. That post covered the problem. This one covers the solution: running BM25 and vector search in parallel, merging results, and reranking with a cross-encoder.

BM25 handles:

Exact product names and SKUs
Brand names ("Nike", "Bosch")
Specific attributes ("size 38", "500ml", "red")

Vector search handles:

Natural language descriptions ("something warm for winter")
Intent-based queries ("gift for a coffee lover")
Cross-language queries (customer asks in German, catalog is in English)

How the Merge Works

Both searches return scored results. The trick is normalizing scores so they're comparable, then combining them with configurable weights.

def hybrid_search(query: str, store_id: str, limit: int = 20):
    # Run both searches in parallel
    bm25_results = bm25_search(query, store_id, limit=limit * 2)
    vector_results = vector_search(query, store_id, limit=limit * 2)

    # Normalize scores to 0-1 range
    bm25_scores = normalize(bm25_results)
    vector_scores = normalize(vector_results)

    # Merge with weights (tuned per use case)
    merged = {}
    for product_id, score in bm25_scores.items():
        merged[product_id] = score * BM25_WEIGHT

    for product_id, score in vector_scores.items():
        if product_id in merged:
            merged[product_id] += score * VECTOR_WEIGHT
        else:
            merged[product_id] = score * VECTOR_WEIGHT

    return sorted(merged.items(), key=lambda x: x[1], reverse=True)[:limit]

The weights need tuning per store. Stores with lots of SKU-based lookups benefit from higher BM25 weight. Stores where customers describe what they want (fashion, home goods) benefit from higher vector weight. I don't have a universal formula. Start at 50/50 and adjust based on your query logs.

Cross-Encoder Reranking

After the merge, a cross-encoder reranker compares each candidate directly against the query.

Unlike bi-encoders (which encode query and product separately), cross-encoders take the pair as input and output a relevance score. More expensive, but more accurate.

from sentence_transformers import CrossEncoder

reranker = CrossEncoder("cross-encoder/ms-marco-MiniLM-L-6-v2")

def rerank(query: str, candidates: list[dict]) -> list[dict]:
    pairs = [(query, c["text"]) for c in candidates]
    scores = reranker.predict(pairs)

    for i, candidate in enumerate(candidates):
        candidate["rerank_score"] = float(scores[i])

    return sorted(candidates, key=lambda x: x["rerank_score"], reverse=True)

I run this on the top 20-30 candidates from hybrid search, not the full catalog. This keeps response times reasonable since cross-encoders are slow on large sets.

Note: the code examples above are simplified for clarity. Production code needs error handling, async execution, and score caching.

Cross-Language Search

One side effect of using intfloat/multilingual-e5-large: it maps 100+ languages into the same vector space. A query in French against an English catalog returns correct results because the embedding model treats meaning, not language, as the proximity metric. No translation API needed. If you sell across borders, the multilingual embedding model does the work for free.

What This Doesn't Do

Limitations:

Image search. Customers can't upload a photo and find matching products. This is a different problem requiring CLIP or similar models.
Personalization. The search doesn't learn from individual user behavior. It treats every query independently.
Typo correction. Heavy typos can throw off both BM25 and vector search. I handle this with query preprocessing, but it's not perfect.
Real-time inventory. Search returns products that exist in the catalog. Stock availability is a separate check.

What I've Seen in Practice

I don't have clean A/B test data to share yet. What I can say from manually testing across several store catalogs:

Keyword-only search fails on most natural language queries. If the customer doesn't use the exact product name, they get nothing.
Vector-only search handles descriptions well but returns wrong results for SKU lookups and specific attributes (color, size).
Hybrid search with reranking handles both query types. SKU searches still work. Descriptive queries return relevant products.

I won't put a percentage on it until I have proper metrics. If you're building this, set up evaluation before you ship.

The data sync pipeline that feeds this search engine handles 60,000+ product catalogs with batch embeddings and hash-based skip logic. I wrote about that in Syncing 60,000 Products Without Breaking Everything.

I built this as part of Emporiqa. There's a deeper dive on how product search works end-to-end on the Emporiqa blog. You can test hybrid search on your own catalog with a free sandbox — 100 products, no credit card.

Syncing 60,000 Products Without Breaking Everything

Rosen Hristov — Fri, 20 Feb 2026 13:48:23 +0000

A dental supply store with 60,000 products wants to sync their catalog to my search engine. Every product needs a vector embedding. Here's what I learned about not melting the server.

Why Webhooks, Not Pull

The first architectural decision was whether my system should pull data from stores or let stores push data to it.

Pull-based sync sounds simpler: hit the store's API on a schedule, diff the results, update what changed. In practice it falls apart. You need to poll every store on some interval, deal with pagination across different APIs, handle rate limits on the store's side, and figure out what changed since last time. If you support multiple platforms (Drupal, WooCommerce, Sylius, custom), every platform has a different API shape.

I went with webhook-only. Stores push events to a single endpoint: POST /webhooks/sync/{store_id}/. The payload is a list of typed events:

{
  "events": [
    {"type": "product.created", "data": {"identification_number": "SKU-123", "sku": "...", "names": {"default": {"en": "..."}}, ...}},
    {"type": "product.updated", "data": {"identification_number": "SKU-456", "sku": "...", "names": {"default": {"en": "..."}}, ...}}
  ]
}

Nine event types total: product.created, product.updated, product.deleted, and the same for pages, plus sync.start, sync.complete, and order.completed. Every event goes through a Pydantic schema before anything happens. Invalid payload? 400 response before it ever hits a queue.

The tradeoff is real: now every store integration has to implement webhook sending. But I ship official modules for Drupal and WooCommerce that handle it, and for everything else there's a documented webhook API. The upside is the system never needs to know how any store's API works.

The Processing Pipeline

A webhook request hits the endpoint and goes through five checks before anything gets queued:

Rate limit (120 requests per 60 seconds per store, sliding window in Redis)
Store lookup (does this store_id exist?)
Subscription check (is the subscription active?)
HMAC-SHA256 signature (every store has an encrypted webhook secret, auto-generated on creation)
Schema validation (every event validated against its Pydantic model)

If all five pass, the events go to Celery:

process_webhook_events.delay(store.id, events_data)

The endpoint returns 202 immediately. The store doesn't wait for embeddings or database writes. The Celery task picks it up, and WebhookProcessor.process_events() handles the actual work.

One detail that cost me a bug: sync session item registration happens synchronously at webhook receipt time, before Celery picks up the events. I'll explain why in the reconciliation section.

Hash-Based Skip Logic

Generating an embedding for a product is the expensive part. The embedding model runs in a separate inference service (a FastAPI app with a sentence transformer), and each call takes real time. For 60,000 products, you can't regenerate every embedding on every sync.

Each product has a content hash: a SHA-256 of its embedding prompt (name, SKU, category, brand, description, attributes). When a product.updated event comes in, the processor looks up the existing product in Qdrant and compares hashes:

existing = self.qdrant_service.get_product_by_identification_number(
    store.id, data.identification_number
)

if existing and existing.get("hash") == product.hash:
    if not self._product_has_non_hash_changes(product, existing):
        return  # nothing changed, skip entirely
    # only price/stock/images changed, reuse existing embedding
    product.embedding = existing.get("embedding")

Three outcomes:

Hash matches, no other changes: skip entirely. No embedding, no write.
Hash matches, but price/stock/images changed: reuse the existing embedding, update only the mutable fields.
Hash differs: generate new embedding, write everything.

In a typical "full resync" of 60,000 products where maybe 200 actually changed, this skips embedding generation for 59,800 of them.

Batch Processing

Product create and update events get special treatment. Instead of processing one at a time, they're collected and run through a three-phase batch pipeline:

Phase 1 (Collect): Build product objects, check subscription limits, hash-check against Qdrant. Products that need new embeddings go in one list; products that can reuse existing embeddings go in another.

Phase 2 (Batch embed): One call to the inference service's /embed/batch endpoint per batch of 50 products. Instead of 200 individual HTTP calls, you get 4.

Phase 3 (Batch upsert): One Qdrant upsert for all products.

texts = [p.get_embedding_prompt() for p in products_needing_embedding]
embeddings = embedding_service.generate_embeddings_batch(texts)

for product, embedding in zip(products_needing_embedding, embeddings, strict=True):
    product.embedding = embedding

The batch size of 50 for the inference service is a tuned number. Higher and the inference service starts timing out. Lower and the HTTP overhead adds up.

Full Sync Reconciliation

Incremental webhooks handle the common case: a store updates a product, sends product.updated, done. But what about products that got deleted on the store side and no one sent a product.deleted? What about data drift after weeks of intermittent sync failures?

That's what full sync reconciliation solves. The protocol is three steps:

Store sends sync.start with a session_id, entity ("products" or "pages"), and channel
Store sends every product as product.created or product.updated, each with a sync_session_id field — all translations consolidated in one event
Store sends sync.complete

The system tracks which items it saw during the session. When sync.complete arrives, anything in Qdrant that wasn't seen gets soft-deleted.

The session state lives in Redis with a 24-hour TTL:

# Key structure
f"sync_session:{store_id}:{entity}:{channel}"    # stores the session_id
f"sync_items:{store_id}:{entity}:{channel}:{session_id}"  # stores a set of seen IDs

When each event arrives at the webhook endpoint, the item's identification_number gets added to the seen-items set before the event is queued to Celery:

def _register_sync_items(self, store_id, events):
    for event in events:
        sync_session_id = event.data.get("sync_session_id")
        if not sync_session_id:
            continue
        SyncSessionService.register_item(
            store_id, entity, channel, sync_session_id, identification_number
        )

This was a bug fix. Originally I registered items during Celery processing. But Celery tasks run asynchronously, and if the store sent sync.complete in a separate request that arrived while product events were still queued, the seen-items set was incomplete. Items got deleted that shouldn't have been. Moving registration to the synchronous webhook handler fixed the race condition.

On sync.complete, the processor gets all product IDs from Qdrant, diffs them against the seen set, and soft-deletes the rest:

all_products = self.qdrant_service.get_all_product_ids(store.id, channel)
for identification_number in all_products:
    if identification_number not in seen_items:
        # soft-delete: set deleted=True in Qdrant

What Broke Along the Way

The sync registration race condition was the worst one. A store would sync 60,000 products across hundreds of webhook requests, then send sync.complete. But Celery hadn't finished processing all the product events yet, so the seen-items set was missing thousands of entries. The cleanup step would delete products that were still being processed. I noticed because a store reported half their catalog vanishing after a sync. The fix was registering items at the webhook endpoint, not in the Celery worker.

Subscription limit tracking during batch processing had a similar counting bug. The _check_product_limit method queries Qdrant for the current count, but during batch processing, new products haven't been upserted yet. If a store on a 2,000-product plan sent 100 new products in one batch, the limit check saw the same count for all 100 and let them all through. I added an in-memory counter (new_product_counts dict, keyed by channel) that tracks how many new products have been approved within the current batch.

Inference service timeouts with large batches. My first implementation sent all products needing embeddings in one HTTP call. With 500 products, the inference service would take 30+ seconds and the HTTP client would time out. Chunking into batches of 50 with a separate INFERENCE_SERVICE_BATCH_TIMEOUT setting fixed it.

What's Still Not Great

The seen-items set for sync sessions is stored as a Python set in Redis (via Django's cache framework). For a 60,000-product catalog, that's 60,000 strings in memory. A Redis set with SADD/SMEMBERS would be more memory-efficient. Haven't hit a wall yet, but it's on the list.

The reconciliation cleanup iterates over every product ID and does individual lookups and updates. For very large catalogs with thousands of deletions, this is slow. Qdrant's filtering doesn't support "not in this set of IDs" directly, so there's no bulk shortcut.

There's no retry logic at the event level. The Celery task retries up to 3 times on failure, but that retries the entire batch — re-doing hash checks and Qdrant lookups for products that already succeeded. Single-product failures get logged and skipped, which is correct. Full inference service outages are the painful case.

The Drupal side of this pipeline — entity hooks, queue workers, alter hooks for customization — is an official module on drupal.org. I wrote about how it handles Drupal's schema flexibility in Building a Chat Assistant Module for Drupal Commerce. The webhook documentation covers the full event schema and authentication setup for any platform. You can see the full pipeline working with a free sandbox — syncs up to 100 products in about 2 minutes.

Building a Chat Assistant Module for Drupal Commerce

Rosen Hristov — Fri, 20 Feb 2026 13:46:14 +0000

Most e-commerce integrations follow the same playbook: install a plugin, give it API credentials, let it pull data from your store on a schedule. This works on Shopify. It works on WooCommerce (mostly). On Drupal Commerce, it falls apart.

Drupal Commerce stores are not uniform. Two stores might both sell shoes, but one uses product variations with attribute fields, the other uses referenced paragraph entities with field collections. One has a custom "brand" taxonomy, the other stores brand as a plain text field on the product. Content types, field configurations, display modes: everything is configurable.

I spent 12 years building Drupal sites before I started working on Emporiqa, a chat assistant for e-commerce stores. When it came time to build the Drupal integration, I had to make a choice: try to query every possible Drupal schema from the outside, or let Drupal tell me what the data looks like.

I went with webhooks. The module pushes data out. The external service never queries Drupal directly.

Why Webhooks Instead of an API Client

The pull-based approach means writing an API client that understands your store's schema. What fields exist on commerce_product? Which field holds the brand? Where are the images? Is that a media reference or a direct file field? Are variations inline or referenced?

You end up building a Drupal-specific API consumer that needs to handle every field type, every entity reference, every display configuration. And it breaks whenever someone adds a custom field or changes a view mode.

The webhook approach inverts this. The Drupal module already has full access to the entity system. It knows the field types, the references, the translations. It builds the payload on the Drupal side, where all that context is available, and sends a flat JSON payload to the webhook endpoint.

The receiving side gets a standardized structure regardless of how the Drupal store is configured internally:

{
  "type": "product.created",
  "data": {
    "identification_number": "product-42",
    "sku": "HB-GTX-42",
    "channels": ["1"],
    "names": {"1": {"en": "Hiking Boot GTX", "de": "Wanderstiefel GTX"}},
    "descriptions": {"1": {"en": "Waterproof hiking boot with...", "de": "Wasserdichter Wanderstiefel mit..."}},
    "links": {"1": {"en": "https://store.com/hiking-boot-gtx", "de": "https://store.com/de/wanderstiefel-gtx"}},
    "categories": {"1": {"en": ["Footwear"], "de": ["Schuhe"]}},
    "brands": {"1": "Salomon"},
    "prices": {"1": [
      {"currency": "USD", "current_price": 159.99, "regular_price": 189.99}
    ]},
    "availability_statuses": {"1": "available"},
    "attributes": {"1": {"en": {"material": "Gore-Tex", "weight": "450g"}, "de": {"Material": "Gore-Tex", "Gewicht": "450g"}}},
    "images": {"1": ["https://store.com/boot-1.jpg"]}
  }
}

The module handles extracting categories from taxonomy references, brand from whatever field type the store uses, images from media entities or file fields. All translations are bundled into a single webhook event — one event per product, with nested language keys.

Entity Hooks, Not cron

Products sync when they change, not on a schedule. The module hooks into Drupal's entity CRUD events using the OOP hook pattern (Drupal 10.3+):

// In EmporiqaHooks:
public function commerceProductInsert(ProductInterface $product): void {
    $this->queueProductEvent($product, 'created');
}

public function commerceProductUpdate(ProductInterface $product): void {
    $this->queueProductEvent($product, 'updated');
}

public function commerceProductDelete(ProductInterface $product): void {
    $this->queueProductEvent($product, 'deleted');
}
// ... same for variations and nodes

When a store admin saves a product, the hook fires, builds the webhook payload, and drops it into Drupal's queue system. A queue worker picks it up and sends the HTTP request. If the request fails (network issue, timeout), the queue retries.

This is standard Drupal: entity hooks, QueueInterface, QueueWorkerBase. Nothing unusual. If you have built a custom sync module before, this pattern is familiar.

The queue part matters. Sending webhooks synchronously during entity save would slow down the admin UI. Product saves should feel instant. The webhook can happen a few seconds later, in the background.

Display Modes for Field Mapping

Here is the part that took the most iteration. The module needs to know which fields to include in the webhook payload. Hardcoding field names ("field_brand", "field_image") would break on every store that uses different names.

The module auto-detects available fields during installation: taxonomy references for category and brand, image fields, description fields. It stores the mapping in configuration. The settings form at /admin/config/services/emporiqa lets you adjust which fields map to what.

For products, this config-based field mapping is the primary approach. The store developer picks "field_brand" from a dropdown, not by writing PHP. Automatic detection on install means most stores get reasonable defaults without touching the settings form.

For pages and advanced use cases, the module also supports a custom emporiqa view mode. If configured, the module renders the entity using that display mode and uses the output. This is useful when you need computed fields or complex field formatters to produce the right text.

Alter Hooks: Eight Extension Points

Drupal developers expect hooks. The module provides eight:

hook_emporiqa_entity_sync_alter controls whether an entity syncs at all:

function mymodule_emporiqa_entity_sync_alter(bool &$sync, EntityInterface $entity, string $entity_type, string $operation) {
  // Skip draft products
  if ($entity->get('moderation_state')->value !== 'published') {
    $sync = FALSE;
  }

  // Skip products in a specific category
  $category = $entity->get('field_category')->entity;
  if ($category && $category->label() === 'Internal Only') {
    $sync = FALSE;
  }
}

hook_emporiqa_data_alter modifies the payload before it is sent:

function mymodule_emporiqa_data_alter(array &$data, array &$context) {
  $entity = $context['entity'];

  // Add vehicle compatibility from a custom field.
  // Attributes use consolidated format: {channel: {lang: value}}.
  if ($entity->hasField('field_vehicle_compatibility')) {
    $vehicles = [];
    foreach ($entity->get('field_vehicle_compatibility') as $item) {
      $vehicles[] = $item->entity->label();
    }
    foreach ($data['attributes'] as $channel => &$languages) {
      foreach ($languages as $lang => &$attrs) {
        $attrs['compatible_vehicles'] = implode(', ', $vehicles);
      }
    }
  }
}

hook_emporiqa_channels_alter assigns products to sales channels:

function mymodule_emporiqa_channels_alter(array &$channels, ProductInterface $product): void {
  // Assign products to channels based on their Commerce stores.
  foreach ($product->getStores() as $store) {
    if ($store->get('field_channel')->value) {
      $channels[] = $store->get('field_channel')->value;
    }
  }
}

hook_emporiqa_tier_prices_alter provides volume discount tiers:

function mymodule_emporiqa_tier_prices_alter(array &$tier_prices, array $context): void {
  $variation = $context['variation'];
  if ($variation->hasField('field_tier_prices')) {
    foreach ($variation->get('field_tier_prices') as $item) {
      $tier_prices[] = [
        'min_quantity' => (int) $item->min_qty,
        'price' => (float) $item->price,
        'currency' => $context['currency'],
      ];
    }
  }
}

hook_emporiqa_price_entry_alter modifies individual price entries (e.g., add tax-inclusive/exclusive prices):

function mymodule_emporiqa_price_entry_alter(array &$price_entry, array $context): void {
  // Add tax-inclusive price alongside the default tax-exclusive price.
  $price_entry['price_incl_tax'] = $price_entry['current_price'] * 1.21;
}

hook_emporiqa_cart_alter intercepts cart operations before they execute:

function mymodule_emporiqa_cart_alter(array &$context): void {
  // Enforce maximum quantity per item
  if ($context['operation'] === 'add' && $context['data']['quantity'] > 10) {
    $context['cancel'] = TRUE;
    $context['cancel_message'] = 'Maximum 10 items per product.';
  }
}

hook_emporiqa_checkout_route_alter overrides the checkout route used for cart checkout URL generation:

function mymodule_emporiqa_checkout_route_alter(string &$route_name): void {
  // Use a custom checkout route instead of the default.
  $route_name = 'my_custom_checkout.form';
}

hook_emporiqa_order_tracking_alter provides custom order lookup for non-Commerce order systems:

function mymodule_emporiqa_order_tracking_alter(?array &$response, string $order_identifier, array $body) {
  // Look up from external ERP
  $order = my_erp_get_order($order_identifier);
  if ($order) {
    $response = [
      'order_id' => $order->id,
      'status' => $order->status,
      'placed_at' => $order->created_at,
      'items' => $order->items,
    ];
  }
}

All eight hooks live in your custom module, not in the Emporiqa module. When the module updates via Composer, your customizations stay untouched.

I used the data_alter pattern on an auto parts store. Products had vehicle compatibility stored as entity references to a "Vehicle" content type with year/make/model fields. The hook flattened that into a comma-separated string in the attributes field, so the chat assistant could answer "Does this fit a 2019 Ford Focus?" without needing to understand Drupal's entity reference system.

Full Sync and Reconciliation

Real-time entity hooks handle most cases. But what about products that existed before the module was installed? Or data that got out of sync after a server migration?

Drush commands handle bulk sync:

drush emporiqa:sync-products    # Sync all products (alias: em:sp)
drush emporiqa:sync-pages       # Sync pages (alias: em:spg)
drush emporiqa:sync-all         # Both at once (alias: em:sa)
drush emporiqa:test-connection  # Verify webhook connectivity (alias: em:tc)

You can also trigger a full sync from the admin UI — the Sync tab at /admin/config/services/emporiqa runs the sync with a Batch API progress bar. No command line needed.

The sync uses a session-based reconciliation protocol: the Drush command sends sync.start, then every product with a session ID attached, then sync.complete. The receiving side tracks which products it saw during the session and soft-deletes anything missing. This handles "I deleted 50 products from Drupal while the module was disabled" cleanly.

The --batch-size flag controls memory usage for large catalogs. For stores with 20,000+ products, dropping it to 25 keeps things under control.

I wrote about the receiving side of this pipeline — batch embeddings, hash-based skip logic, and the reconciliation race condition that deleted half a catalog — in Syncing 60,000 Products Without Breaking Everything.

Cart Operations and Conversion Tracking

Two features that go beyond sync:

In-chat cart operations. The module provides cart API endpoints that work with commerce_cart directly. Customers can add products to cart, update quantities, and proceed to checkout from the chat conversation. The cart_alter hook lets you intercept operations (enforce limits, validate items) without touching the module.

Conversion tracking. An event subscriber listens for Commerce order completion and sends an order.completed webhook. This links the chat session to the purchase, so you can see chat-attributed revenue on the dashboard.

Order Tracking

The module provides a built-in endpoint at /emporiqa/api/order/tracking. If Commerce Order is installed, it works out of the box: looks up orders by order number, returns status, items, and totals. Email verification is enabled by default — the customer must provide the email used on the order before any data is returned.

For non-Commerce order systems (external ERP, custom tables), implement hook_emporiqa_order_tracking_alter() to provide your own lookup logic.

Order tracking is optional. If you don't configure it, customers asking about orders get routed to the customer support agent instead.

Multilingual

The module works with Drupal's translation system. Products sync with all translations in a single webhook event — names, descriptions, categories, and attributes are nested by channel and language code. If you have English, German, and French translations, they are all bundled into one payload per product. The chat widget detects the customer's language from the embed tag and returns responses in that language.

What This Doesn't Cover

Variation complexity. Drupal Commerce variations (sizes, colors) are their own entities. The module syncs parent products and variations separately. The chat assistant stitches them back together at query time. This works for standard variation structures but may need the data_alter hook for highly customized setups.
Custom pricing. The webhook payload sends prices as a channel-keyed object (e.g., {"": [...]}) where each channel contains an array of price entries per currency (each has current_price, optional regular_price, tax fields, and volume tier prices). This covers multi-currency, multi-channel, and B2B scenarios, but complex discount rules (dynamic coupon codes, customer-group pricing) still need the store to compute the final price before sending.
Custom pricing. The webhook payload sends prices as a channel-keyed object (e.g., {"1": [...]}) where each channel contains an array of price entries per currency (each has current_price, optional regular_price, tax fields, and volume tier prices). This covers multi-currency, multi-channel, and B2B scenarios, but complex discount rules (dynamic coupon codes, customer-group pricing) still need the store to compute the final price before sending.
Private products. The module syncs all published products by default. If some products should only be visible to specific user roles, you need to use the entity_sync_alter hook to filter them out.

The Module Structure

For developers who want to look at the code:

emporiqa/
  emporiqa.info.yml           # Module definition
  emporiqa.module             # Hook bridge (delegates to EmporiqaHooks)
  emporiqa.services.yml       # Service definitions
  emporiqa.install            # Install/uninstall, field auto-detection
  emporiqa.api.php            # Hook documentation
  drush.services.yml          # Drush command registration
  composer.json               # Dependencies
  config/
    install/                  # Default configuration
    optional/                 # Optional config
    schema/                   # Config schema
  js/                         # Widget embedding scripts
  src/
    Hook/                     # OOP entity hook handlers (EmporiqaHooks)
    EventSubscriber/          # Order completion events
    Plugin/
      QueueWorker/            # Async webhook delivery
    Form/                     # Settings + sync forms
    Controller/               # Order tracking, cart, user token
    Commands/                 # Drush commands (sync, test-connection)
    Service/                  # Webhook client, data formatting, sync

Standard Drupal module layout. Service injection, plugin-based workers, YAML configuration. No custom tables, no schema alterations. It installs and uninstalls cleanly.

The module is an official module on drupal.org. Works with Drupal 10.3+ and 11.x, Commerce 2.40+ and 3.x, PHP 8.1+. The setup and installation guide covers everything from Composer install to field mapping. I also wrote about the full integration story on the Emporiqa blog. If you want to try it on a real store, the sandbox is free — 100 products, no credit card.

I Built Vector-Only Search First. Here's Why I Had to Rewrite It.

Rosen Hristov — Fri, 20 Feb 2026 06:32:07 +0000

I spent three weeks building a pure vector search for an e-commerce product catalog. Embedded everything with multilingual-e5-large, loaded it into Qdrant, and ran my first test queries.

"Gift for someone who likes cooking" returned kitchen knives and spice sets. Great.

"Nike Air Max 90 black" returned Adidas running shoes.

"XJ-4520" (an actual product SKU) returned a random kitchen appliance.

I had a semantic search engine that understood meaning but couldn't handle the simplest exact-match lookup.

What Vector Search Is Good At

Embeddings map text into a high-dimensional space where similar meanings cluster together. When a customer types "gift for someone who likes cooking," the embedding lands near kitchen knives, cookbooks, and spice sets, even though none of those products contain the word "gift."

For descriptive queries, it works well. I tested it across five languages and the model (intfloat/multilingual-e5-large) mapped them all into the same space. A query in Bulgarian against an English catalog returned correct results. No translation layer, no language detection. Just math.

Where It Fell Apart

SKUs and model numbers. "XJ-4520" is a meaningless string to an embedding model. It gets projected somewhere in vector space, and the nearest neighbors are whatever other meaningless strings happen to be nearby. In my tests, SKU lookups almost never returned the right product.

Brand + attribute combos. "Nike Air Max 90 black size 42" should return exactly one product. Vector search returned Nike products, but also Adidas and Puma, because they're all semantically "athletic shoes." The exact match was sometimes on page two.

Numeric filters. "Under $50" or "500ml bottle" — embeddings don't understand numbers as constraints. They understand that 500ml is semantically related to "bottle" and "liquid," but they won't filter by numeric value.

Short, specific queries. When a customer types just "Bosch" with nothing else, vector search returned random power tools. BM25 would return all Bosch products ranked by relevance.

The Fix: Add BM25 Back

I ended up running BM25 and vector search in parallel against the same catalog, then merging results with normalized scores.

BM25 handles exact matches: SKUs, brand names, specific attributes. Vector search handles everything else: descriptive queries, intent-based searches, cross-language.

The merge is the interesting part. Both engines return scored results, but the scores aren't comparable (BM25 scores can be 0-25+, vector similarity is 0-1). You have to normalize both to the same range before combining.

def normalize_scores(results: dict[str, float]) -> dict[str, float]:
    if not results:
        return {}
    min_score = min(results.values())
    max_score = max(results.values())
    if max_score == min_score:
        return {k: 1.0 for k in results}
    return {
        k: (v - min_score) / (max_score - min_score)
        for k, v in results.items()
    }

After normalization, I combine with configurable weights. The right ratio depends on the store. A parts supplier where customers search by part number needs heavier BM25. A fashion store where customers describe what they want needs heavier vector.

What I Learned

Don't start with vector-only. Every tutorial I read at the time said "just embed your documents and search." None of them mentioned that exact-match queries break completely.

BM25 is underrated. It's a 30-year-old algorithm and still the best thing we have for exact token matching. Qdrant added built-in BM25 support, which means you can run both in the same database without maintaining Elasticsearch on the side.

Test with real queries, not demo queries. My initial tests all used descriptive sentences like "gift for a coffee lover." Those are the queries vector search is designed for. The moment I tested with what actual customers type (brand names, SKUs, "red shoes"), the problems showed up.

Cross-encoder reranking cleans up the merge. After combining BM25 and vector results, I run a cross-encoder (ms-marco-MiniLM-L-6-v2) on the top candidates. It compares each result directly against the query and re-sorts. This catches cases where the merge ranked something incorrectly.

Edge Cases in the Merge

Tutorials stop at "combine the scores." In production:

What if BM25 returns 50 results and vector returns 3? The merge skews heavily toward BM25.
What if the query is a single word? Vector search works poorly on single tokens.
What about queries that are half descriptive, half specific? "Red Nike something for running" needs both engines equally.

I handle some of these with query analysis before search. If the query looks like a SKU (alphanumeric, no spaces), I skip vector search entirely. If it's a long descriptive sentence, I weight vector higher. But it's not clean. There's no universal solution. You tune it per store and keep adjusting.

Limitations

I haven't built image search. A customer can't upload a photo and find matching products.
Typo handling is basic. Heavy misspellings confuse both BM25 and vector search.
No personalization. Every query is independent — the system doesn't learn from a customer's browsing history.
Score caching adds complexity. Embeddings are expensive to compute per request, so I cache them, but cache invalidation on product updates is its own problem.

If you want the implementation details — cross-encoder reranking, score normalization, per-store weight tuning — I wrote a follow-up: Hybrid Search for E-commerce: When Keywords Alone Fail.

I built this as part of Emporiqa, a chat assistant for e-commerce stores. The search runs on Qdrant (vector + BM25 in a single database), intfloat/multilingual-e5-large for embeddings, and ms-marco-MiniLM-L-6-v2 for reranking. I wrote more about how the search approach evolved and what it looks like in production. You can test it on your own catalog with a free sandbox — 100 products, no credit card.