This module is part of the AI module ecosystem and included in DXPR CMS.
- -Transform your content marketing with AI Sorting - the Drupal module that automatically learns which content engages your audience and promotes it for maximum impact. Stop guessing what works and let machine learning optimize your content visibility.- -
Unlike static content lists, AI Sorting delivers:
- -Spin up DXPR CMS—Drupal pre-configured with DXPR Builder, DXPR Theme, AI Sorting module, and security best practices.
- -AI Sorting is built on the powerful Reinforcement Learning (RL) module, which provides the core Thompson Sampling algorithm and experiment tracking capabilities. For developers building custom AI-powered features, the RL module offers a comprehensive API for multi-armed bandit experiments.
- -Ready to supercharge your content marketing? Install AI Sorting and turn your static content lists into intelligent, self-optimizing marketing tools that work 24/7 to maximize engagement.
\ No newline at end of file diff --git a/js/ai-sorting-rewards.js b/js/ai-sorting-rewards.js deleted file mode 100644 index bcb1d3d..0000000 --- a/js/ai-sorting-rewards.js +++ /dev/null @@ -1,47 +0,0 @@ -(function (Drupal, once) { - 'use strict'; - - Drupal.behaviors.aiSortingRewards = { - attach: function (context, settings) { - if (!settings.aiSorting || !settings.aiSorting.views) { - return; - } - - once('ai-sorting-rewards', '.view', context).forEach(function(view) { - var viewIdClass = Array.from(view.classList).find(cls => cls.startsWith('view-id-')); - var viewId = viewIdClass ? viewIdClass.replace('view-id-', '') : 'unknown'; - - if (settings.aiSorting.views[viewId]) { - var viewSettings = settings.aiSorting.views[viewId]; - var experimentUuid = viewSettings.experimentUuid; - var nidUrlMap = viewSettings.nidUrlMap; - var rlEndpointUrl = viewSettings.rlEndpointUrl; - - if (nidUrlMap && Object.keys(nidUrlMap).length > 0) { - var links = view.querySelectorAll('a'); - - links.forEach(function(link) { - var href = link.getAttribute('href'); - var nid = Object.keys(nidUrlMap).find(nid => nidUrlMap[nid] === href); - - if (nid) { - link.dataset.nid = nid; - - link.addEventListener('click', function() { - // Create FormData for POST request to rl.php - var formData = new FormData(); - formData.append('action', 'reward'); - formData.append('experiment_uuid', experimentUuid); - formData.append('arm_id', nid); - - // Use sendBeacon for non-blocking request - navigator.sendBeacon(rlEndpointUrl, formData); - }); - } - }); - } - } - }); - } - }; -})(Drupal, once); \ No newline at end of file diff --git a/js/ai-sorting-tracking.js b/js/ai-sorting-tracking.js new file mode 100644 index 0000000..ce76bfa --- /dev/null +++ b/js/ai-sorting-tracking.js @@ -0,0 +1,86 @@ +(function (Drupal, once) { + 'use strict'; + + Drupal.behaviors.aiSortingTracking = { + attach: function (context, settings) { + if (!settings.aiSorting || !settings.aiSorting.views) { + return; + } + + once('ai-sorting-tracking', '.view', context).forEach(function(view) { + var viewIdClass = Array.from(view.classList).find(cls => cls.startsWith('view-id-')); + var viewId = viewIdClass ? viewIdClass.replace('view-id-', '') : 'unknown'; + + if (!settings.aiSorting.views[viewId]) { + return; + } + + var viewSettings = settings.aiSorting.views[viewId]; + var experimentUuid = viewSettings.experimentUuid; + var entityIds = viewSettings.entityIds; + var entityUrlMap = viewSettings.entityUrlMap; + var rlEndpointUrl = viewSettings.rlEndpointUrl; + + // Fail hard if required data is missing + if (!experimentUuid || !rlEndpointUrl) { + throw new Error('AI Sorting: Missing required experiment data (experimentUuid or rlEndpointUrl)'); + } + + // Track turns (when view becomes visible) + if (entityIds && entityIds.length > 0) { + var observer = new IntersectionObserver(function(entries) { + if (entries[0].isIntersecting) { + // Create FormData for POST request to rl.php + var formData = new FormData(); + formData.append('action', 'turns'); + formData.append('experiment_uuid', experimentUuid); + formData.append('arm_ids', entityIds.join(',')); + + // Use sendBeacon for non-blocking request + var success = navigator.sendBeacon(rlEndpointUrl, formData); + if (!success) { + console.warn('AI Sorting: Failed to send turns data to RL endpoint'); + } + + observer.unobserve(view); + } + }, {threshold: 0.1}); + + observer.observe(view); + } else { + console.warn('AI Sorting: No entity IDs found for turns tracking'); + } + + // Track rewards (when links are clicked) + if (entityUrlMap && Object.keys(entityUrlMap).length > 0) { + var links = view.querySelectorAll('a'); + + links.forEach(function(link) { + var href = link.getAttribute('href'); + var entityId = Object.keys(entityUrlMap).find(id => entityUrlMap[id] === href); + + if (entityId) { + link.dataset.entityId = entityId; + + link.addEventListener('click', function() { + // Create FormData for POST request to rl.php + var formData = new FormData(); + formData.append('action', 'reward'); + formData.append('experiment_uuid', experimentUuid); + formData.append('arm_id', entityId); + + // Use sendBeacon for non-blocking request + var success = navigator.sendBeacon(rlEndpointUrl, formData); + if (!success) { + console.warn('AI Sorting: Failed to send reward data to RL endpoint for entity ' + entityId); + } + }); + } + }); + } else { + console.warn('AI Sorting: No entity URL map found for rewards tracking'); + } + }); + } + }; +})(Drupal, once); \ No newline at end of file diff --git a/js/ai-sorting-turns.js b/js/ai-sorting-turns.js deleted file mode 100644 index 105721d..0000000 --- a/js/ai-sorting-turns.js +++ /dev/null @@ -1,44 +0,0 @@ -(function (Drupal, once) { - 'use strict'; - - Drupal.behaviors.aiSortingTurns = { - attach: function (context, settings) { - if (!settings.aiSorting || !settings.aiSorting.views) { - return; - } - - once('ai-sorting-turns', '.view', context).forEach(function(view) { - var viewIdClass = Array.from(view.classList).find(cls => cls.startsWith('view-id-')); - var viewId = viewIdClass ? viewIdClass.replace('view-id-', '') : 'unknown'; - - if (settings.aiSorting.views[viewId]) { - var viewSettings = settings.aiSorting.views[viewId]; - var experimentUuid = viewSettings.experimentUuid; - var nids = viewSettings.nids; - var rlEndpointUrl = viewSettings.rlEndpointUrl; - - if (nids && nids.length > 0) { - - var observer = new IntersectionObserver(function(entries) { - if (entries[0].isIntersecting) { - - // Create FormData for POST request to rl.php - var formData = new FormData(); - formData.append('action', 'turns'); - formData.append('experiment_uuid', experimentUuid); - formData.append('arm_ids', nids.join(',')); - - // Use sendBeacon for non-blocking request - navigator.sendBeacon(rlEndpointUrl, formData); - - observer.unobserve(view); - } - }, {threshold: 0.1}); - - observer.observe(view); - } - } - }); - } - }; -})(Drupal, once); \ No newline at end of file diff --git a/src/Decorator/AiSortingExperimentDecorator.php b/src/Decorator/AiSortingExperimentDecorator.php deleted file mode 100644 index 3b035f4..0000000 --- a/src/Decorator/AiSortingExperimentDecorator.php +++ /dev/null @@ -1,84 +0,0 @@ -entityTypeManager = $entity_type_manager; - } - - /** - * {@inheritdoc} - */ - public function decorateExperiment(string $uuid): ?array { - // Check if this UUID follows the AI Sorting pattern (sha1 of view:display) - $view_storage = $this->entityTypeManager->getStorage('view'); - $views = $view_storage->loadMultiple(); - - foreach ($views as $view) { - /** @var \Drupal\views\ViewEntityInterface $view */ - foreach ($view->get('display') as $display_id => $display) { - $test_uuid = sha1($view->id() . ':' . $display_id); - if ($test_uuid === $uuid) { - // Found matching view and display. - $view_url = Url::fromRoute('entity.view.edit_form', ['view' => $view->id()]); - $view_link = Link::fromTextAndUrl($view->label(), $view_url); - - return [ - '#markup' => $view_link->toString() . ' (' . $display_id . ')', - ]; - } - } - } - - return NULL; - } - - /** - * {@inheritdoc} - */ - public function decorateArm(string $experiment_uuid, string $arm_id): ?array { - // For AI Sorting, arm_id should be a node ID. - if (is_numeric($arm_id)) { - try { - $node = $this->entityTypeManager->getStorage('node')->load($arm_id); - if ($node) { - $node_url = Url::fromRoute('entity.node.canonical', ['node' => $node->id()]); - $node_link = Link::fromTextAndUrl($node->label(), $node_url); - - return [ - '#markup' => $node_link->toString(), - ]; - } - } - catch (\Exception $e) { - // If node loading fails, fall back to raw arm_id. - } - } - - return NULL; - } - -} diff --git a/src/Plugin/views/sort/AISorting.php b/src/Plugin/views/sort/AISorting.php index 8b918d8..1511149 100644 --- a/src/Plugin/views/sort/AISorting.php +++ b/src/Plugin/views/sort/AISorting.php @@ -98,28 +98,79 @@ public function query() { $experiment_uuid = sha1($this->view->id() . ':' . $this->view->current_display); - // Only apply time window if "Favor recent content" is enabled. - $time_window_seconds = NULL; - if ($this->options['favor_recent']) { - $time_window_seconds = $this->options['time_window_seconds']; + $time_window_seconds = $this->options['favor_recent'] ? $this->options['time_window_seconds'] : NULL; + + // Get the base field from the view configuration. + $base_field = $this->view->storage->get('base_field'); + + // If no base field is defined, we can't sort. + if (empty($base_field)) { + throw new \RuntimeException('AI Sorting requires a base_field to be defined in the view.'); + } + + // Get all possible arm IDs that will be in the result set. + // We need to execute a query to get these IDs. + $arm_ids = []; + + // Clone the current query to get IDs without affecting the main query. + // The view's query at this point has all filters/conditions applied. + $id_query = clone $this->query; + + // We only need the base field (ID field). + // Clear fields and add only the base field. + $id_query->clearFields(); + $id_alias = $id_query->addField($this->tableAlias, $base_field); + + // Remove any existing grouping and ordering. + $id_query->groupby = []; + $id_query->orderby = []; + $id_query->addGroupBy($id_alias); + + // Build and execute the query to get all IDs. + // The query() method returns a SelectQuery object. + $query_obj = $id_query->query(); + + // Remove limit and offset from the query object. + $query_obj->range(); + + $result = $query_obj->execute(); + + foreach ($result as $row) { + if (isset($row->$base_field)) { + $arm_ids[] = (string) $row->$base_field; + } } + // Pass all arm IDs to the RL module to get scores. + // The RL module will handle new arms by initializing them. $scores = $this->experimentManager->getThompsonScores( $experiment_uuid, - $time_window_seconds + $time_window_seconds, + $arm_ids ); + // Fail hard if RL module doesn't return scores - no silent fallbacks! if (empty($scores)) { throw new \RuntimeException(sprintf( - 'No scores for experiment "%s". Check RL tracking.', + 'AI Sorting FAILED: No scores returned for experiment "%s". RL module must always return scores for requested arms. Check RL module configuration and database connectivity.', $experiment_uuid )); } - $case_statement = 'CASE ' . $this->tableAlias . '.nid '; - foreach ($scores as $nid => $score) { - $case_statement .= "WHEN " . (int) $nid . " THEN " . (float) $score . " "; + // Build the CASE statement for sorting. + $case_statement = 'CASE ' . $this->tableAlias . '.' . $base_field . ' '; + + foreach ($scores as $arm_id => $score) { + if (is_numeric($arm_id)) { + $case_statement .= "WHEN " . (int) $arm_id . " THEN " . (float) $score . " "; + } + else { + $escaped_id = addslashes($arm_id); + $case_statement .= "WHEN '" . $escaped_id . "' THEN " . (float) $score . " "; + } } + + // This should never be reached since we passed all IDs to RL module. $case_statement .= 'ELSE 0 END'; $this->query->addOrderBy( diff --git a/src/Service/ExperimentRegistrationService.php b/src/Service/ExperimentRegistrationService.php index 329bcf3..c26467a 100644 --- a/src/Service/ExperimentRegistrationService.php +++ b/src/Service/ExperimentRegistrationService.php @@ -31,9 +31,11 @@ public function __construct(ExperimentRegistryInterface $experiment_registry) { * * @param string $uuid * The experiment UUID to register. + * @param string $experiment_name + * Optional human-readable experiment name. */ - public function registerExperiment(string $uuid): void { - $this->experimentRegistry->register($uuid, 'ai_sorting'); + public function registerExperiment(string $uuid, ?string $experiment_name = NULL): void { + $this->experimentRegistry->register($uuid, 'ai_sorting', $experiment_name); } } diff --git a/src/Service/ExperimentResolver.php b/src/Service/ExperimentResolver.php deleted file mode 100644 index 0b8f200..0000000 --- a/src/Service/ExperimentResolver.php +++ /dev/null @@ -1,43 +0,0 @@ -experimentManager = $experiment_manager; - } - - /** - * Calculates and updates total trials for a view. - * - * @param \Drupal\views\ViewExecutable $view - * The view executable. - * - * @return int - * The total trials count. - */ - public function calculateAndUpdateTotalTrials(ViewExecutable $view) { - $experiment_uuid = sha1($view->id() . ':' . $view->current_display); - return $this->experimentManager->getTotalTurns($experiment_uuid); - } - - /** - * Gets total trials for a specific experiment. - * - * @param string $view_id - * The view ID. - * @param string $display_id - * The display ID. - * - * @return int - * The total trials count. - */ - public function getTotalTrials($view_id, $display_id) { - $experiment_uuid = sha1($view_id . ':' . $display_id); - return $this->experimentManager->getTotalTurns($experiment_uuid); - } - -}