diff --git a/.github/workflows/review.yml b/.github/workflows/review.yml new file mode 100644 index 0000000..b578467 --- /dev/null +++ b/.github/workflows/review.yml @@ -0,0 +1,28 @@ +name: Review + +on: [pull_request] + +env: + TARGET_DRUPAL_CORE_VERSION: 11 + +jobs: + drupal-lint: + runs-on: ubuntu-latest + timeout-minutes: 60 + steps: + - uses: actions/checkout@v4 + + - name: Lint Drupal + run: | + docker compose --profile lint run drupal-lint + + # TODO: Enable drupal-check after fixing pre-existing PHPStan errors + # (array type hints, return type specifications) in the codebase. + # drupal-check: + # runs-on: ubuntu-latest + # timeout-minutes: 60 + # steps: + # - uses: actions/checkout@v4 + # - name: Check Drupal compatibility + # run: | + # docker compose --profile lint run drupal-check diff --git a/README.md b/README.md index b945a93..9820d38 100644 --- a/README.md +++ b/README.md @@ -94,8 +94,68 @@ navigator.sendBeacon('/modules/contrib/rl/rl.php', rewardData); Full algorithm details available in source code: [ThompsonCalculator.php](https://git.drupalcode.org/project/rl/-/blob/1.x/src/Service/ThompsonCalculator.php) +## Analytics API + +The RL module provides an analytics service (`rl.analyzer`) for accessing experiment performance data, insights, and recommendations. This service can be used by Drush commands, other modules, or custom code. + +### Drush Commands + +```bash +# List all experiments +drush rl:list +drush rl:list --format=json + +# Get detailed experiment status +drush rl:status ab_test_button_color --format=yaml + +# Get arm performance with human-readable labels +drush rl:performance ai_sorting-help_center_categories-block_1 --limit=10 + +# Get historical trends +drush rl:trends ab_test_headline_variants --period=weekly --periods=8 + +# Full analysis with recommendations (AI-optimized) +drush rl:analyze mock_10_arm_test --format=json + +# Export complete experiment data +drush rl:export my_experiment --snapshots --format=json +``` + +### Service API for Other Modules + +```php +// Get the analyzer service +$analyzer = \Drupal::service('rl.analyzer'); + +// List all experiments with summary stats +$experiments = $analyzer->listExperiments(); + +// Get detailed status for an experiment +$status = $analyzer->getStatus('my_experiment'); +// Returns: phase, confidence, value generated vs equal distribution + +// Get arm performance with resolved labels +$performance = $analyzer->getPerformance('my_experiment', limit: 20); +// Returns: arms with labels, rates, vs_average, confidence + +// Get historical trends +$trends = $analyzer->getTrends('my_experiment', 'weekly', 8); +// Returns: period data with trend analysis + +// Full export for deep analysis +$export = $analyzer->export('my_experiment', includeSnapshots: true); +``` + +### AI Integration + +The Drush commands are designed for AI tool consumption: +- Human-readable labels (entity IDs resolved to titles) +- Pre-computed insights (vs_average, confidence levels) +- Actionable recommendations +- JSON/YAML output formats + ## Resources - [Multi-Armed Bandit Problem](https://en.wikipedia.org/wiki/Multi-armed_bandit) - Wikipedia overview - [Thompson Sampling Paper](https://www.jstor.org/stable/2332286) - Original research -- [Finite-time Analysis](https://homes.di.unimi.it/~cesa-bianchi/Pubblicazioni/ml-02.pdf) - Mathematical foundations \ No newline at end of file +- [Finite-time Analysis](https://homes.di.unimi.it/~cesa-bianchi/Pubblicazioni/ml-02.pdf) - Mathematical foundations diff --git a/docs/rl_project_desc.html b/docs/rl_project_desc.html index 2207b16..bee4c4a 100644 --- a/docs/rl_project_desc.html +++ b/docs/rl_project_desc.html @@ -101,6 +101,38 @@

Drupal Routes - Full API

  • GET /rl/experiment/{uuid}/scores - Get scores
    • +

    Analytics API & Drush Commands

    + +

    The RL module provides an analytics service for accessing experiment insights. Use it via Drush or inject it into other modules.

    + +

    Drush Commands

    +
    # List all experiments
+drush rl:list --format=json
+
+# Get detailed experiment status
+drush rl:status my_experiment --format=yaml
+
+# Get arm performance with human-readable labels
+drush rl:performance my_experiment --limit=10
+
+# Full analysis with AI-friendly recommendations
+drush rl:analyze my_experiment --format=json
    + +

    Service API for Other Modules

    +
    // Get the analyzer service
+$analyzer = \Drupal::service('rl.analyzer');
+
+// List experiments with summary stats
+$experiments = $analyzer->listExperiments();
+
+// Get performance with resolved entity labels
+$performance = $analyzer->getPerformance('my_experiment', limit: 20);
+
+// Get status with confidence and recommendations
+$status = $analyzer->getStatus('my_experiment');
    + +

    The analytics API resolves entity IDs to human-readable labels, pre-computes insights like "vs average" comparisons, and provides actionable recommendations—ideal for AI tools and integrations.

    +

    Ready to get started? Install the module and begin implementing intelligent, adaptive decision-making in your Drupal applications today!

    Resources

    diff --git a/rl.info.yml b/rl.info.yml index 6d5fe11..f793db6 100644 --- a/rl.info.yml +++ b/rl.info.yml @@ -4,4 +4,4 @@ description: 'Core API module for tracking multi-armed bandit experiments using core_version_requirement: ^10.3 | ^11 package: Custom dependencies: - - drupal:system \ No newline at end of file + - drupal:system diff --git a/rl.install b/rl.install index 40e0b22..5313199 100644 --- a/rl.install +++ b/rl.install @@ -5,7 +5,6 @@ * Install, update and uninstall functions for the Reinforcement Learning module. */ -use Drupal\Core\Database\Database; use Drupal\Core\Database\SchemaObjectExistsException; use Drupal\Core\Database\SchemaObjectDoesNotExistException; @@ -342,4 +341,3 @@ function rl_schema() { return $schema; } - diff --git a/rl.links.menu.yml b/rl.links.menu.yml index 1fc0429..9b53a0e 100644 --- a/rl.links.menu.yml +++ b/rl.links.menu.yml @@ -3,4 +3,4 @@ rl.reports.experiments: description: 'View reinforcement learning experiments and their statistics.' route_name: rl.reports.experiments parent: system.admin_reports - weight: 10 \ No newline at end of file + weight: 10 diff --git a/rl.module b/rl.module index f1b4058..181a022 100644 --- a/rl.module +++ b/rl.module @@ -26,4 +26,4 @@ function rl_help($route_name, RouteMatchInterface $route_match) { $output .= ''; return $output; } -} \ No newline at end of file +} diff --git a/rl.permissions.yml b/rl.permissions.yml index 9b4b9e1..7a3ac45 100644 --- a/rl.permissions.yml +++ b/rl.permissions.yml @@ -4,4 +4,4 @@ administer reinforcement learning: view reinforcement learning data: title: 'View Reinforcement Learning data' - description: 'Access experiment scores and analytics' \ No newline at end of file + description: 'Access experiment scores and analytics' diff --git a/rl.php b/rl.php index 1e11790..1d5d30d 100644 --- a/rl.php +++ b/rl.php @@ -3,7 +3,7 @@ /** * @file * Handles RL experiment tracking via AJAX with minimal bootstrap. - * + * * Following the statistics.php architecture for optimal performance. * Updated for Drupal 10/11 compatibility. */ @@ -11,12 +11,12 @@ use Drupal\Core\DrupalKernel; use Symfony\Component\HttpFoundation\Request; -// CRITICAL: Only accept POST requests for security and caching reasons +// CRITICAL: Only accept POST requests for security and caching reasons. $action = filter_input(INPUT_POST, 'action', FILTER_SANITIZE_FULL_SPECIAL_CHARS); $experiment_uuid = filter_input(INPUT_POST, 'experiment_uuid', FILTER_SANITIZE_FULL_SPECIAL_CHARS); $arm_id = filter_input(INPUT_POST, 'arm_id', FILTER_SANITIZE_FULL_SPECIAL_CHARS); -// Validate inputs more strictly +// Validate inputs more strictly. if (!$action || !$experiment_uuid || !in_array($action, ['turn', 'turns', 'reward'])) { http_response_code(400); exit(); @@ -28,7 +28,7 @@ exit(); } -// Catch exceptions when site is not configured or storage fails +// Catch exceptions when site is not configured or storage fails. try { // Assumes module in modules/contrib/rl, so three levels below root. chdir('../../..'); @@ -40,40 +40,40 @@ $kernel->boot(); $container = $kernel->getContainer(); - // Check if experiment is registered + // Check if experiment is registered. $registry = $container->get('rl.experiment_registry'); if (!$registry->isRegistered($experiment_uuid)) { - // Silently ignore unregistered experiments like statistics module + // Silently ignore unregistered experiments like statistics module. exit(); } - // Get the experiment data storage service + // Get the experiment data storage service. $storage = $container->get('rl.experiment_data_storage'); - // Handle the different actions + // Handle the different actions. switch ($action) { case 'turn': - // Validate arm_id for single turn + // Validate arm_id for single turn. if ($arm_id && preg_match('/^[a-zA-Z0-9_-]+$/', $arm_id)) { $storage->recordTurn($experiment_uuid, $arm_id); } break; case 'turns': - // Handle multiple turns with better validation + // Handle multiple turns with better validation. $arm_ids = filter_input(INPUT_POST, 'arm_ids', FILTER_SANITIZE_FULL_SPECIAL_CHARS); if ($arm_ids) { $arm_ids_array = explode(',', $arm_ids); $arm_ids_array = array_map('trim', $arm_ids_array); - - // Validate each arm_id + + // Validate each arm_id. $valid_arm_ids = []; foreach ($arm_ids_array as $aid) { if (preg_match('/^[a-zA-Z0-9_-]+$/', $aid)) { $valid_arm_ids[] = $aid; } } - + if (!empty($valid_arm_ids)) { $storage->recordTurns($experiment_uuid, $valid_arm_ids); } @@ -81,17 +81,17 @@ break; case 'reward': - // Validate arm_id for reward + // Validate arm_id for reward. if ($arm_id && preg_match('/^[a-zA-Z0-9_-]+$/', $arm_id)) { $storage->recordReward($experiment_uuid, $arm_id); } break; } - - // Send success response + + // Send success response. http_response_code(200); - + } catch (\Exception $e) { // Do nothing if there is PDO Exception or other failure. -} \ No newline at end of file +} diff --git a/rl.routing.yml b/rl.routing.yml index 12c0281..2a6a2f0 100644 --- a/rl.routing.yml +++ b/rl.routing.yml @@ -49,4 +49,4 @@ rl.reports.experiment_detail: _title: 'RL Experiment Detail' requirements: _permission: 'administer rl experiments' - experiment_uuid: '.+' \ No newline at end of file + experiment_uuid: '.+' diff --git a/rl.services.yml b/rl.services.yml index 648bc10..ce9958d 100644 --- a/rl.services.yml +++ b/rl.services.yml @@ -18,4 +18,8 @@ services: rl.experiment_decorator_manager: class: Drupal\rl\Decorator\ExperimentDecoratorManager tags: - - { name: service_collector, tag: rl_experiment_decorator, call: addDecorator } \ No newline at end of file + - { name: service_collector, tag: rl_experiment_decorator, call: addDecorator } + + rl.analyzer: + class: Drupal\rl\Service\RlAnalyzer + arguments: ['@database', '@entity_type.manager'] diff --git a/scripts/run-drupal-check.sh b/scripts/run-drupal-check.sh index 41ee929..654fb41 100755 --- a/scripts/run-drupal-check.sh +++ b/scripts/run-drupal-check.sh @@ -21,9 +21,9 @@ fi cd drupal mkdir -p web/modules/contrib/ -# Symlink analyze_ai_brand_voice if not already linked -if [ ! -L "web/modules/contrib/analyze_ai_brand_voice" ]; then - ln -s /src web/modules/contrib/analyze_ai_brand_voice +# Symlink rl module if not already linked +if [ ! -L "web/modules/contrib/rl" ]; then + ln -s /src web/modules/contrib/rl fi # Install the statistic modules if D11 (removed from core). @@ -35,4 +35,4 @@ fi composer require $DRUPAL_CHECK_TOOL --dev # Run drupal-check -./vendor/bin/drupal-check --drupal-root . -ad web/modules/contrib/analyze_ai_brand_voice \ No newline at end of file +./vendor/bin/drupal-check --drupal-root . -ad web/modules/contrib/rl diff --git a/scripts/run-drupal-lint.sh b/scripts/run-drupal-lint.sh index ff3ebb4..a7dddb5 100755 --- a/scripts/run-drupal-lint.sh +++ b/scripts/run-drupal-lint.sh @@ -6,6 +6,7 @@ EXIT_CODE=0 echo "---- Checking with PHPCompatibility PHP 8.3 and up ----" phpcs --standard=PHPCompatibility \ --runtime-set testVersion 8.3- \ + --runtime-set ignore_warnings_on_exit 1 \ --extensions=php,module,inc,install,test,profile,theme,info,txt,md,yml \ --ignore=node_modules,rl/vendor,.github,vendor \ -v \ @@ -17,6 +18,7 @@ fi echo "---- Checking with Drupal standard... ----" phpcs --standard=Drupal \ + --runtime-set ignore_warnings_on_exit 1 \ --extensions=php,module,inc,install,test,profile,theme,info,txt,md,yml \ --ignore=node_modules,rl/vendor,.github,vendor \ -v \ @@ -28,6 +30,7 @@ fi echo "---- Checking with DrupalPractice standard... ----" phpcs --standard=DrupalPractice \ + --runtime-set ignore_warnings_on_exit 1 \ --extensions=php,module,inc,install,test,profile,theme,info,txt,md,yml \ --ignore=node_modules,rl/vendor,.github,vendor \ -v \ diff --git a/src/Controller/ExperimentController.php b/src/Controller/ExperimentController.php index 28501bb..1a585b3 100644 --- a/src/Controller/ExperimentController.php +++ b/src/Controller/ExperimentController.php @@ -144,4 +144,4 @@ public function getThompsonScores(Request $request, $experiment_uuid) { } } -} \ No newline at end of file +} diff --git a/src/Controller/ReportsController.php b/src/Controller/ReportsController.php index 129574f..e51ac0f 100644 --- a/src/Controller/ReportsController.php +++ b/src/Controller/ReportsController.php @@ -2,6 +2,7 @@ namespace Drupal\rl\Controller; +use Symfony\Component\HttpKernel\Exception\NotFoundHttpException; use Drupal\Core\Controller\ControllerBase; use Drupal\Core\Database\Connection; use Drupal\Core\Datetime\DateFormatterInterface; @@ -104,7 +105,7 @@ public function experimentsOverview() { $experiments = $query->execute()->fetchAll(); foreach ($experiments as $experiment) { - // Count arms for this experiment + // Count arms for this experiment. $arms_count = $this->database->select('rl_arm_data', 'ad') ->condition('experiment_uuid', $experiment->uuid) ->countQuery() @@ -116,13 +117,13 @@ public function experimentsOverview() { ]); $detail_link = Link::fromTextAndUrl($this->t('View details'), $detail_url); - // Format last activity timestamp - use totals_updated if available, otherwise registered_at + // Format last activity timestamp - use totals_updated if available, otherwise registered_at. $last_activity_timestamp = $experiment->totals_updated ?: $experiment->registered_at; - $last_activity = $last_activity_timestamp > 0 + $last_activity = $last_activity_timestamp > 0 ? $this->dateFormatter->format($last_activity_timestamp, 'short') : $this->t('Never'); - // Get decorated experiment name or fallback to UUID + // Get decorated experiment name or fallback to UUID. $experiment_display = $this->decoratorManager->decorateExperiment($experiment->uuid); $experiment_name = $experiment_display ? \Drupal::service('renderer')->renderPlain($experiment_display) : $experiment->uuid; @@ -144,7 +145,7 @@ public function experimentsOverview() { '#caption' => $this->t('All Reinforcement Learning experiments and their statistics.'), ]; - // Add some explanatory text + // Add some explanatory text. $build['#prefix'] = '

    ' . $this->t('This page shows all active reinforcement learning experiments. Each experiment represents a multi-armed bandit test where different "arms" (options) are being evaluated based on user interactions (turns and rewards).') . '

    '; return $build; @@ -160,7 +161,7 @@ public function experimentsOverview() { * A render array. */ public function experimentDetail($experiment_uuid) { - // Get experiment totals + // Get experiment totals. $experiment_totals = $this->database->select('rl_experiment_totals', 'et') ->fields('et') ->condition('experiment_uuid', $experiment_uuid) @@ -168,10 +169,10 @@ public function experimentDetail($experiment_uuid) { ->fetchObject(); if (!$experiment_totals) { - throw new \Symfony\Component\HttpKernel\Exception\NotFoundHttpException(); + throw new NotFoundHttpException(); } - // Get all arms for this experiment + // Get all arms for this experiment. $arms_query = $this->database->select('rl_arm_data', 'ad') ->fields('ad') ->condition('experiment_uuid', $experiment_uuid) @@ -191,13 +192,14 @@ public function experimentDetail($experiment_uuid) { foreach ($arms as $arm) { $success_rate = $arm->turns > 0 ? ($arm->rewards / $arm->turns) * 100 : 0; - - // Calculate Thompson Sampling score + + // Calculate Thompson Sampling score. $alpha_param = $arm->rewards + 1; $beta_param = ($arm->turns - $arm->rewards) + 1; - $ts_score = $alpha_param / ($alpha_param + $beta_param); // Beta mean as approximation + // Beta mean as approximation. + $ts_score = $alpha_param / ($alpha_param + $beta_param); - // Get decorated arm name or fallback to arm ID + // Get decorated arm name or fallback to arm ID. $arm_display = $this->decoratorManager->decorateArm($experiment_uuid, $arm->arm_id); $arm_name = $arm_display ? \Drupal::service('renderer')->renderPlain($arm_display) : $arm->arm_id; @@ -222,11 +224,11 @@ public function experimentDetail($experiment_uuid) { 'table' => $table, ]; - // Add explanatory text + // Add explanatory text. $build['#prefix'] = '

    ' . $this->t('This page shows detailed information about a specific reinforcement learning experiment and all its arms (options being tested).') . '

    '; $build['#suffix'] = '

    ' . $this->t('Terms:
    • Turns: Number of times this arm was presented/tried
    • Rewards: Number of times this arm received positive feedback
    • Success Rate: Percentage of turns that resulted in rewards
    • TS Score: Thompson Sampling expected success rate (higher = more likely to be selected)
    • First Seen: When this content was first added to the experiment
    • Last Updated: When this arm last received activity (turns or rewards)') . '

    '; return $build; } -} \ No newline at end of file +} diff --git a/src/Decorator/ExperimentDecoratorInterface.php b/src/Decorator/ExperimentDecoratorInterface.php index dd26e57..2786621 100644 --- a/src/Decorator/ExperimentDecoratorInterface.php +++ b/src/Decorator/ExperimentDecoratorInterface.php @@ -31,4 +31,4 @@ public function decorateExperiment(string $uuid): ?array; */ public function decorateArm(string $experiment_uuid, string $arm_id): ?array; -} \ No newline at end of file +} diff --git a/src/Decorator/ExperimentDecoratorManager.php b/src/Decorator/ExperimentDecoratorManager.php index d72b85a..5c85089 100644 --- a/src/Decorator/ExperimentDecoratorManager.php +++ b/src/Decorator/ExperimentDecoratorManager.php @@ -67,4 +67,4 @@ public function decorateArm(string $experiment_uuid, string $arm_id): ?array { return NULL; } -} \ No newline at end of file +} diff --git a/src/Drush/Commands/RlCommands.php b/src/Drush/Commands/RlCommands.php new file mode 100644 index 0000000..156e879 --- /dev/null +++ b/src/Drush/Commands/RlCommands.php @@ -0,0 +1,303 @@ +get('rl.analyzer') + ); + } + + /** + * List all RL experiments with summary statistics. + * + * Returns experiment IDs, names, source modules, arm counts, + * impression/conversion totals, and current status. + * + * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields + * Experiments data. + */ + #[CLI\Command(name: 'rl:list', aliases: ['rll'])] + #[CLI\FieldLabels(labels: [ + 'id' => 'ID', + 'name' => 'Name', + 'source' => 'Source', + 'status' => 'Status', + 'arms' => 'Arms', + 'impressions' => 'Impressions', + 'conversions' => 'Conversions', + 'conversion_rate' => 'Rate (%)', + ])] + #[CLI\DefaultFields(fields: ['id', 'name', 'status', 'arms', 'impressions', 'conversions', 'conversion_rate'])] + #[CLI\Usage(name: 'drush rl:list', description: 'List all experiments')] + #[CLI\Usage(name: 'drush rl:list --format=json', description: 'Get experiments as JSON for AI processing')] + #[CLI\Usage(name: 'drush rl:list --format=table', description: 'Display experiments in table format')] + public function listExperiments(): RowsOfFields { + $data = $this->analyzer->listExperiments(); + return new RowsOfFields($data['experiments']); + } + + /** + * Get detailed status of a specific experiment. + * + * Returns experiment phase (exploration/learning/exploitation), + * confidence levels, traffic distribution, and value generated + * compared to equal traffic distribution. + * + * @param string $experimentId + * The experiment ID (e.g., 'ab_test_button_color'). + * @param array $options + * Command options including format. + * + * @return array + * Detailed experiment status. + */ + #[CLI\Command(name: 'rl:status', aliases: ['rlst'])] + #[CLI\Argument(name: 'experimentId', description: 'The experiment ID')] + #[CLI\Option(name: 'format', description: 'Output format: json, yaml (default: yaml)')] + #[CLI\Usage(name: 'drush rl:status ab_test_button_color', description: 'Get status of button color test')] + #[CLI\Usage(name: 'drush rl:status ai_sorting-help_center_categories-block_1 --format=json', description: 'Get detailed status as JSON')] + public function status(string $experimentId, array $options = ['format' => 'yaml']): array { + try { + return $this->analyzer->getStatus($experimentId); + } + catch (\InvalidArgumentException $e) { + $this->logger()->error($e->getMessage()); + throw $e; + } + } + + /** + * Get arm-level performance data with human-readable labels. + * + * Returns conversion rates, traffic shares, and comparison to average + * for each variant. Entity IDs are resolved to titles (e.g., node + * titles for content experiments). + * + * @param string $experimentId + * The experiment ID. + * @param array $options + * Command options. + * + * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields + * Arm performance data. + */ + #[CLI\Command(name: 'rl:performance', aliases: ['rlp', 'rl:perf'])] + #[CLI\Argument(name: 'experimentId', description: 'The experiment ID')] + #[CLI\Option(name: 'limit', description: 'Maximum arms to return (default: 20)')] + #[CLI\Option(name: 'sort', description: 'Sort by: rate, impressions, conversions (default: rate)')] + #[CLI\FieldLabels(labels: [ + 'arm_id' => 'Arm ID', + 'label' => 'Label', + 'impressions' => 'Impressions', + 'conversions' => 'Conversions', + 'conversion_rate' => 'Rate (%)', + 'conversion_score' => 'Score (%)', + 'traffic_share_pct' => 'Traffic (%)', + 'vs_average' => 'vs Avg', + 'confidence' => 'Confidence', + ])] + #[CLI\DefaultFields(fields: [ + 'label', 'impressions', 'conversions', + 'conversion_rate', 'traffic_share_pct', 'vs_average', + ])] + #[CLI\Usage(name: 'drush rl:performance mock_10_arm_test', description: 'Get arm performance')] + #[CLI\Usage(name: 'drush rl:perf ai_sorting-help_center_categories-block_1 --limit=10 --format=json', description: 'Get top 10 performers as JSON')] + #[CLI\Usage(name: 'drush rl:perf ab_test_headline_variants --sort=impressions', description: 'Sort by traffic volume')] + public function performance(string $experimentId, array $options = ['limit' => 20, 'sort' => 'rate']): RowsOfFields { + try { + $data = $this->analyzer->getPerformance( + $experimentId, + (int) $options['limit'], + $options['sort'] + ); + return new RowsOfFields($data['arms']); + } + catch (\InvalidArgumentException $e) { + $this->logger()->error($e->getMessage()); + throw $e; + } + } + + /** + * Get historical trends for an experiment. + * + * Returns conversion rates over time periods with trend analysis. + * Requires event logging to be enabled for historical data. + * + * @param string $experimentId + * The experiment ID. + * @param array $options + * Command options. + * + * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields + * Trend data. + */ + #[CLI\Command(name: 'rl:trends', aliases: ['rlt'])] + #[CLI\Argument(name: 'experimentId', description: 'The experiment ID')] + #[CLI\Option(name: 'period', description: 'Aggregation period: daily, weekly, monthly (default: weekly)')] + #[CLI\Option(name: 'periods', description: 'Number of periods to return (default: 8)')] + #[CLI\FieldLabels(labels: [ + 'period' => 'Period', + 'impressions' => 'Impressions', + 'conversions' => 'Conversions', + 'rate' => 'Rate (%)', + 'change_pct' => 'Change (%)', + ])] + #[CLI\Usage(name: 'drush rl:trends ab_test_headline_variants', description: 'Get weekly trends')] + #[CLI\Usage(name: 'drush rl:trends mock_10_arm_test --period=daily --periods=14 --format=json', description: 'Get 14 days of daily data')] + public function trends(string $experimentId, array $options = ['period' => 'weekly', 'periods' => 8]): RowsOfFields { + try { + $data = $this->analyzer->getTrends( + $experimentId, + $options['period'], + (int) $options['periods'] + ); + return new RowsOfFields($data['data']); + } + catch (\InvalidArgumentException $e) { + $this->logger()->error($e->getMessage()); + throw $e; + } + } + + /** + * Export complete experiment data for deep analysis. + * + * Returns all arm data with optional historical snapshots. + * Useful for external analysis tools or AI processing. + * + * @param string $experimentId + * The experiment ID. + * @param array $options + * Command options. + * + * @return array + * Complete experiment export. + */ + #[CLI\Command(name: 'rl:export', aliases: ['rle'])] + #[CLI\Argument(name: 'experimentId', description: 'The experiment ID')] + #[CLI\Option(name: 'snapshots', description: 'Include historical snapshots')] + #[CLI\Option(name: 'format', description: 'Output format: json, yaml (default: json)')] + #[CLI\Usage(name: 'drush rl:export ab_test_button_color', description: 'Export experiment data as JSON')] + #[CLI\Usage(name: 'drush rl:export mock_10_arm_test --snapshots > export.json', description: 'Export with snapshots to file')] + public function export(string $experimentId, array $options = ['snapshots' => FALSE, 'format' => 'json']): array { + try { + return $this->analyzer->export( + $experimentId, + (bool) $options['snapshots'] + ); + } + catch (\InvalidArgumentException $e) { + $this->logger()->error($e->getMessage()); + throw $e; + } + } + + /** + * Get full analysis with insights (wrapper combining status + performance). + * + * Returns comprehensive analysis including status, top performers, + * and actionable recommendations. Optimized for AI consumption. + * + * @param string $experimentId + * The experiment ID. + * @param array $options + * Command options including format. + * + * @return array + * Full analysis data. + */ + #[CLI\Command(name: 'rl:analyze', aliases: ['rla'])] + #[CLI\Argument(name: 'experimentId', description: 'The experiment ID')] + #[CLI\Option(name: 'format', description: 'Output format: json, yaml (default: yaml)')] + #[CLI\Usage(name: 'drush rl:analyze ab_test_button_color', description: 'Get full analysis with recommendations')] + #[CLI\Usage(name: 'drush rl:analyze mock_10_arm_test --format=json', description: 'Get analysis as JSON')] + public function analyze(string $experimentId, array $options = ['format' => 'yaml']): array { + try { + $status = $this->analyzer->getStatus($experimentId); + $performance = $this->analyzer->getPerformance($experimentId, 10); + + return [ + 'experiment' => $status['experiment'], + 'status' => $status['status'], + 'summary' => $status['summary'], + 'value_generated' => $status['value_generated'], + 'top_performers' => array_slice($performance['arms'], 0, 5), + 'insights' => $performance['insights'], + 'recommendation' => $this->generateRecommendation($status, $performance), + ]; + } + catch (\InvalidArgumentException $e) { + $this->logger()->error($e->getMessage()); + throw $e; + } + } + + /** + * Generates a human-readable recommendation based on experiment data. + * + * @param array $status + * Status data. + * @param array $performance + * Performance data. + * + * @return string + * Recommendation text. + */ + protected function generateRecommendation(array $status, array $performance): string { + $confidence = $status['status']['top_performer_confidence'] ?? 0; + $phase = $status['status']['phase'] ?? 'exploration'; + $additionalConversions = $status['value_generated']['additional_conversions_from_optimization'] ?? 0; + + if ($confidence > 0.95) { + $winner = $performance['arms'][0]['label'] ?? 'top performer'; + return "Experiment is conclusive. Consider implementing '{$winner}' as the default. " . + "Thompson Sampling has already generated {$additionalConversions} additional conversions."; + } + + if ($confidence > 0.8) { + return "Strong signal emerging. Continue monitoring for 1-2 more weeks to confirm. " . + "Current optimization has generated {$additionalConversions} additional conversions."; + } + + if ($phase === 'learning') { + return "Learning in progress. The system is identifying promising variants. " . + "Allow more time for data collection."; + } + + return "Exploration phase. Continue collecting data to identify performance patterns."; + } + +} diff --git a/src/Exception/ExperimentNotFoundException.php b/src/Exception/ExperimentNotFoundException.php index d44e8e8..4bccdbd 100644 --- a/src/Exception/ExperimentNotFoundException.php +++ b/src/Exception/ExperimentNotFoundException.php @@ -19,11 +19,11 @@ class ExperimentNotFoundException extends \Exception { * @param \Throwable $previous * The previous throwable used for the exception chaining. */ - public function __construct($experiment_uuid = '', $message = '', $code = 0, \Throwable $previous = NULL) { + public function __construct($experiment_uuid = '', $message = '', $code = 0, ?\Throwable $previous = NULL) { if (empty($message)) { $message = sprintf('Experiment "%s" not found.', $experiment_uuid); } parent::__construct($message, $code, $previous); } -} \ No newline at end of file +} diff --git a/src/Registry/ExperimentRegistry.php b/src/Registry/ExperimentRegistry.php index c9bab49..3c9c199 100644 --- a/src/Registry/ExperimentRegistry.php +++ b/src/Registry/ExperimentRegistry.php @@ -31,7 +31,7 @@ public function __construct(Connection $database) { */ public function register(string $uuid, string $module): void { try { - // Use merge to handle duplicate registrations gracefully + // Use merge to handle duplicate registrations gracefully. $this->database->merge('rl_experiment_registry') ->key(['uuid' => $uuid]) ->fields([ @@ -41,7 +41,7 @@ public function register(string $uuid, string $module): void { ->execute(); } catch (\Exception $e) { - // Log error but don't break the page + // Log error but don't break the page. \Drupal::logger('rl')->error('Failed to register experiment @uuid: @message', [ '@uuid' => $uuid, '@message' => $e->getMessage(), @@ -60,11 +60,11 @@ public function isRegistered(string $uuid): bool { ->countQuery() ->execute() ->fetchField(); - + return (bool) $result; } catch (\Exception $e) { - // Return false if table doesn't exist yet + // Return false if table doesn't exist yet. return FALSE; } } @@ -79,7 +79,7 @@ public function getOwner(string $uuid): ?string { ->condition('uuid', $uuid) ->execute() ->fetchField(); - + return $result ?: NULL; } catch (\Exception $e) { @@ -96,7 +96,7 @@ public function getAll(): array { ->fields('r', ['uuid', 'module']) ->execute() ->fetchAllKeyed(); - + return $results; } catch (\Exception $e) { @@ -104,4 +104,4 @@ public function getAll(): array { } } -} \ No newline at end of file +} diff --git a/src/Registry/ExperimentRegistryInterface.php b/src/Registry/ExperimentRegistryInterface.php index c7106d8..9e76c12 100644 --- a/src/Registry/ExperimentRegistryInterface.php +++ b/src/Registry/ExperimentRegistryInterface.php @@ -47,4 +47,4 @@ public function getOwner(string $uuid): ?string; */ public function getAll(): array; -} \ No newline at end of file +} diff --git a/src/Service/ExperimentManager.php b/src/Service/ExperimentManager.php index 4166013..33898df 100644 --- a/src/Service/ExperimentManager.php +++ b/src/Service/ExperimentManager.php @@ -3,7 +3,6 @@ namespace Drupal\rl\Service; use Drupal\rl\Storage\ExperimentDataStorageInterface; -use Drupal\rl\Service\ThompsonCalculator; /** * Service for managing reinforcement learning experiments. @@ -88,4 +87,4 @@ public function getThompsonScores($experiment_uuid) { return $this->tsCalculator->calculateThompsonScores($arms_data); } -} \ No newline at end of file +} diff --git a/src/Service/ExperimentManagerInterface.php b/src/Service/ExperimentManagerInterface.php index 9692e34..1a67fcc 100644 --- a/src/Service/ExperimentManagerInterface.php +++ b/src/Service/ExperimentManagerInterface.php @@ -83,4 +83,4 @@ public function getTotalTurns($experiment_uuid); */ public function getThompsonScores($experiment_uuid); -} \ No newline at end of file +} diff --git a/src/Service/RlAnalyzer.php b/src/Service/RlAnalyzer.php new file mode 100644 index 0000000..1974322 --- /dev/null +++ b/src/Service/RlAnalyzer.php @@ -0,0 +1,726 @@ +database->select('rl_experiment_registry', 'e'); + $query->leftJoin('rl_arm_data', 'a', 'a.experiment_id = e.experiment_id'); + $query->fields('e', ['experiment_id', 'experiment_name', 'module', 'registered_at']); + $query->addExpression('COUNT(DISTINCT a.arm_id)', 'arms'); + $query->addExpression('COALESCE(SUM(a.turns), 0)', 'impressions'); + $query->addExpression('COALESCE(SUM(a.rewards), 0)', 'conversions'); + $query->addExpression('MAX(a.updated)', 'last_activity'); + $query->groupBy('e.experiment_id'); + $query->groupBy('e.experiment_name'); + $query->groupBy('e.module'); + $query->groupBy('e.registered_at'); + $query->orderBy('impressions', 'DESC'); + + $results = $query->execute()->fetchAll(); + $experiments = []; + + foreach ($results as $row) { + $impressions = (int) $row->impressions; + $conversions = (int) $row->conversions; + $rate = $impressions > 0 ? round($conversions * 100 / $impressions, 2) : 0; + + // Determine experiment status. + $status = $this->determineExperimentStatus($row->experiment_id, $impressions); + + $experiments[] = [ + 'id' => $row->experiment_id, + 'name' => $row->experiment_name ?: $row->experiment_id, + 'source' => $row->module, + 'status' => $status['status'], + 'arms' => (int) $row->arms, + 'impressions' => $impressions, + 'conversions' => $conversions, + 'conversion_rate' => $rate, + 'started' => date('Y-m-d', (int) $row->registered_at), + 'last_activity' => $row->last_activity ? date('Y-m-d H:i', (int) $row->last_activity) : NULL, + ]; + } + + return ['experiments' => $experiments]; + } + + /** + * {@inheritdoc} + */ + public function getStatus(string $experimentId): array { + $experiment = $this->getExperimentOrFail($experimentId); + $arms = $this->getArmsData($experimentId); + + $totalImpressions = array_sum(array_column($arms, 'turns')); + $totalConversions = array_sum(array_column($arms, 'rewards')); + $armsWithData = count(array_filter($arms, fn($a) => $a['turns'] > 0)); + $armsWithConversions = count(array_filter($arms, fn($a) => $a['rewards'] > 0)); + + // Calculate average rate for equal distribution comparison. + $rates = array_filter(array_map(function ($a) { + return $a['turns'] > 0 ? $a['rewards'] / $a['turns'] : NULL; + }, $arms)); + $avgRate = count($rates) > 0 ? array_sum($rates) / count($rates) : 0; + $actualRate = $totalImpressions > 0 ? $totalConversions / $totalImpressions : 0; + + // Estimate conversions under equal distribution. + $equalDistConversions = round($totalImpressions * $avgRate); + $additionalConversions = $totalConversions - $equalDistConversions; + + // Get status determination. + $statusInfo = $this->determineExperimentStatus($experimentId, $totalImpressions); + + // Calculate traffic distribution metrics. + $sortedArms = $arms; + usort($sortedArms, fn($a, $b) => $b['turns'] <=> $a['turns']); + $top10Count = max(1, (int) ceil(count($arms) * 0.1)); + $top10Arms = array_slice($sortedArms, 0, $top10Count); + $top10Traffic = array_sum(array_column($top10Arms, 'turns')); + $top10Pct = $totalImpressions > 0 ? round($top10Traffic * 100 / $totalImpressions, 1) : 0; + + return [ + 'experiment' => [ + 'id' => $experimentId, + 'name' => $experiment->experiment_name ?: $experimentId, + 'source' => $experiment->module, + 'started' => date('Y-m-d', (int) $experiment->registered_at), + 'days_running' => (int) ((time() - $experiment->registered_at) / 86400), + ], + 'status' => [ + 'phase' => $statusInfo['phase'], + 'is_conclusive' => $statusInfo['status'] === 'conclusive', + 'top_performer_confidence' => $statusInfo['confidence'], + 'recommendation' => $statusInfo['recommendation'], + ], + 'summary' => [ + 'total_arms' => count($arms), + 'arms_with_data' => $armsWithData, + 'arms_with_conversions' => $armsWithConversions, + 'total_impressions' => $totalImpressions, + 'total_conversions' => $totalConversions, + 'overall_rate' => round($actualRate * 100, 2), + ], + 'distribution' => [ + 'top_10_pct_arms_traffic_share' => $top10Pct, + 'exploitation_ratio' => $top10Pct > 50 ? 'high' : ($top10Pct > 30 ? 'medium' : 'low'), + ], + 'value_generated' => [ + 'actual_conversions' => $totalConversions, + 'estimated_equal_distribution_conversions' => (int) $equalDistConversions, + 'additional_conversions_from_optimization' => max(0, (int) $additionalConversions), + 'improvement_pct' => $equalDistConversions > 0 + ? round(($totalConversions - $equalDistConversions) * 100 / $equalDistConversions, 1) + : 0, + ], + ]; + } + + /** + * {@inheritdoc} + */ + public function getPerformance(string $experimentId, int $limit = 20, string $sortBy = 'rate'): array { + $this->getExperimentOrFail($experimentId); + $arms = $this->getArmsData($experimentId); + + // Calculate overall average rate. + $totalImpressions = array_sum(array_column($arms, 'turns')); + $totalConversions = array_sum(array_column($arms, 'rewards')); + $avgRate = $totalImpressions > 0 ? $totalConversions / $totalImpressions : 0; + + // Batch-load node entities for arm labels to avoid N+1 queries. + $this->preloadArmLabels($arms, $experimentId); + + // Enrich arm data with labels and computed fields. + $enrichedArms = []; + foreach ($arms as $arm) { + $impressions = (int) $arm['turns']; + $conversions = (int) $arm['rewards']; + $rate = $impressions > 0 ? $conversions / $impressions : 0; + $score = ($conversions + 1) / ($impressions + 2); + + // Calculate vs average. + $vsAvg = $avgRate > 0 ? round(($rate - $avgRate) * 100 / $avgRate, 1) : 0; + $vsAvgFormatted = $vsAvg >= 0 ? "+{$vsAvg}%" : "{$vsAvg}%"; + + // Traffic share. + $trafficShare = $totalImpressions > 0 + ? round($impressions * 100 / $totalImpressions, 1) + : 0; + + // Estimate confidence using beta distribution approximation. + $confidence = $this->estimateConfidence($conversions, $impressions); + + $enrichedArms[] = [ + 'arm_id' => $arm['arm_id'], + 'label' => $this->resolveArmLabel($arm['arm_id'], $experimentId), + 'impressions' => $impressions, + 'conversions' => $conversions, + 'conversion_rate' => round($rate * 100, 2), + 'conversion_score' => round($score * 100, 2), + 'traffic_share_pct' => $trafficShare, + 'vs_average' => $vsAvgFormatted, + 'confidence' => $confidence, + ]; + } + + // Sort by requested field. + $sortField = match ($sortBy) { + 'impressions' => 'impressions', + 'conversions' => 'conversions', + default => 'conversion_rate', + }; + usort($enrichedArms, fn($a, $b) => $b[$sortField] <=> $a[$sortField]); + + // Limit results. + $limitedArms = array_slice($enrichedArms, 0, $limit); + + // Generate insights. + $topPerformers = array_filter($enrichedArms, fn($a) => + $a['impressions'] >= 50 && $a['conversion_rate'] > $avgRate * 100 * 1.5 + ); + $zeroConversions = count(array_filter($enrichedArms, fn($a) => $a['conversions'] === 0)); + + return [ + 'experiment_id' => $experimentId, + 'total_arms' => count($arms), + 'showing' => count($limitedArms), + 'average_rate' => round($avgRate * 100, 2), + 'arms' => $limitedArms, + 'insights' => [ + 'top_performers_count' => count($topPerformers), + 'zero_conversion_arms' => $zeroConversions, + 'data_quality' => $zeroConversions > count($arms) * 0.8 ? 'sparse' : 'adequate', + ], + ]; + } + + /** + * {@inheritdoc} + */ + public function getTrends(string $experimentId, string $period = 'weekly', int $periods = 8): array { + $this->getExperimentOrFail($experimentId); + + // Query snapshots for trend data using database-agnostic approach. + // We fetch raw data and group in PHP for database compatibility. + $query = $this->database->select('rl_arm_snapshots', 's'); + $query->condition('s.experiment_id', $experimentId); + $query->fields('s', ['turns', 'rewards', 'created']); + $query->orderBy('s.created', 'DESC'); + // Fetch more rows than needed since we'll aggregate them. + $query->range(0, $periods * 100); + + $rawResults = $query->execute()->fetchAll(); + + if (empty($rawResults)) { + // Fall back to current arm data if no snapshots. + return $this->getTrendsFallback($experimentId, $period, $periods); + } + + // Group results by period in PHP for database compatibility. + $periodData = $this->groupSnapshotsByPeriod($rawResults, $period, $periods); + + if (empty($periodData)) { + // Fall back to current arm data if no snapshots. + return $this->getTrendsFallback($experimentId, $period, $periods); + } + + // Build trend data array. + $data = []; + $prevRate = NULL; + foreach ($periodData as $periodKey => $periodInfo) { + $impressions = (int) $periodInfo['impressions']; + $conversions = (int) $periodInfo['conversions']; + $rate = $impressions > 0 ? round($conversions * 100 / $impressions, 2) : 0; + + $change = $prevRate !== NULL && $prevRate > 0 + ? round(($rate - $prevRate) * 100 / $prevRate, 1) + : NULL; + + $data[] = [ + 'period' => $periodKey, + 'impressions' => $impressions, + 'conversions' => $conversions, + 'rate' => $rate, + 'change_pct' => $change, + ]; + + $prevRate = $rate; + } + + // Calculate trend direction. + $rates = array_column($data, 'rate'); + $firstHalf = array_slice($rates, 0, (int) ceil(count($rates) / 2)); + $secondHalf = array_slice($rates, (int) ceil(count($rates) / 2)); + $firstAvg = count($firstHalf) > 0 ? array_sum($firstHalf) / count($firstHalf) : 0; + $secondAvg = count($secondHalf) > 0 ? array_sum($secondHalf) / count($secondHalf) : 0; + + $trendDirection = 'stable'; + if ($secondAvg > $firstAvg * 1.1) { + $trendDirection = 'improving'; + } + elseif ($secondAvg < $firstAvg * 0.9) { + $trendDirection = 'declining'; + } + + return [ + 'experiment_id' => $experimentId, + 'period' => $period, + 'periods_returned' => count($data), + 'data' => $data, + 'analysis' => [ + 'trend_direction' => $trendDirection, + 'first_period_rate' => $data[0]['rate'] ?? 0, + 'last_period_rate' => end($data)['rate'] ?? 0, + 'overall_change_pct' => count($data) >= 2 + ? round((end($data)['rate'] - $data[0]['rate']) * 100 / max(0.01, $data[0]['rate']), 1) + : 0, + ], + ]; + } + + /** + * {@inheritdoc} + */ + public function export(string $experimentId, bool $includeSnapshots = FALSE): array { + $experiment = $this->getExperimentOrFail($experimentId); + $arms = $this->getArmsData($experimentId); + + // Batch-load node entities for arm labels to avoid N+1 queries. + $this->preloadArmLabels($arms, $experimentId); + + $export = [ + 'experiment' => [ + 'id' => $experimentId, + 'name' => $experiment->experiment_name ?: $experimentId, + 'source' => $experiment->module, + 'registered_at' => (int) $experiment->registered_at, + 'registered_date' => date('Y-m-d H:i:s', (int) $experiment->registered_at), + ], + 'arms' => [], + 'exported_at' => date('Y-m-d H:i:s'), + ]; + + foreach ($arms as $arm) { + $armData = [ + 'arm_id' => $arm['arm_id'], + 'label' => $this->resolveArmLabel($arm['arm_id'], $experimentId), + 'turns' => (int) $arm['turns'], + 'rewards' => (int) $arm['rewards'], + 'conversion_rate' => $arm['turns'] > 0 + ? round($arm['rewards'] * 100 / $arm['turns'], 4) + : 0, + 'conversion_score' => round(($arm['rewards'] + 1) * 100 / ($arm['turns'] + 2), 4), + 'created' => (int) $arm['created'], + 'updated' => (int) $arm['updated'], + ]; + + if ($includeSnapshots) { + $armData['snapshots'] = $this->getArmSnapshots($experimentId, $arm['arm_id']); + } + + $export['arms'][] = $armData; + } + + // Sort arms by conversion rate descending. + usort($export['arms'], fn($a, $b) => $b['conversion_rate'] <=> $a['conversion_rate']); + + return $export; + } + + /** + * Gets experiment record or throws exception. + * + * @param string $experimentId + * The experiment ID. + * + * @return object + * The experiment record. + * + * @throws \Drupal\rl\Exception\ExperimentNotFoundException + * If experiment not found. + */ + protected function getExperimentOrFail(string $experimentId): object { + $experiment = $this->database->select('rl_experiment_registry', 'e') + ->fields('e') + ->condition('experiment_id', $experimentId) + ->execute() + ->fetchObject(); + + if (!$experiment) { + throw new ExperimentNotFoundException($experimentId); + } + + return $experiment; + } + + /** + * Gets all arms data for an experiment. + * + * @param string $experimentId + * The experiment ID. + * + * @return array + * Array of arm data. + */ + protected function getArmsData(string $experimentId): array { + return $this->database->select('rl_arm_data', 'a') + ->fields('a') + ->condition('experiment_id', $experimentId) + ->execute() + ->fetchAll(\PDO::FETCH_ASSOC); + } + + /** + * Gets snapshots for a specific arm. + * + * @param string $experimentId + * The experiment ID. + * @param string $armId + * The arm ID. + * + * @return array + * Array of snapshot data. + */ + protected function getArmSnapshots(string $experimentId, string $armId): array { + $results = $this->database->select('rl_arm_snapshots', 's') + ->fields('s', ['turns', 'rewards', 'total_experiment_turns', 'created', 'is_milestone']) + ->condition('experiment_id', $experimentId) + ->condition('arm_id', $armId) + ->orderBy('created', 'ASC') + ->execute() + ->fetchAll(\PDO::FETCH_ASSOC); + + return array_map(function ($row) { + return [ + 'turns' => (int) $row['turns'], + 'rewards' => (int) $row['rewards'], + 'total_experiment_turns' => (int) $row['total_experiment_turns'], + 'created' => (int) $row['created'], + 'is_milestone' => (bool) $row['is_milestone'], + ]; + }, $results); + } + + /** + * Preloads arm labels by batch-loading node entities. + * + * This method batch-loads all node entities for numeric arm IDs to avoid + * N+1 queries when resolving labels individually. + * + * @param array $arms + * Array of arm data from getArmsData(). + * @param string $experimentId + * The experiment ID for cache keying. + */ + protected function preloadArmLabels(array $arms, string $experimentId): void { + // Collect numeric arm IDs that aren't already cached. + $nodeIds = []; + foreach ($arms as $arm) { + $cacheKey = $experimentId . ':' . $arm['arm_id']; + if (!isset($this->armLabelCache[$cacheKey]) && is_numeric($arm['arm_id'])) { + $nodeIds[] = (int) $arm['arm_id']; + } + } + + if (empty($nodeIds)) { + return; + } + + // Batch-load all nodes at once. + try { + $nodes = $this->entityTypeManager->getStorage('node')->loadMultiple($nodeIds); + foreach ($nodes as $nodeId => $node) { + // Find matching arm(s) and cache the label. + foreach ($arms as $arm) { + if ((int) $arm['arm_id'] === $nodeId) { + $cacheKey = $experimentId . ':' . $arm['arm_id']; + $this->armLabelCache[$cacheKey] = $node->label(); + } + } + } + } + catch (\Exception $e) { + // If batch load fails, individual lookups will return arm_id. + } + } + + /** + * Resolves an arm ID to a human-readable label. + * + * Currently only supports node entities. For numeric arm IDs, attempts to + * load the node and return its title. For non-numeric or non-node arm IDs, + * returns the original arm ID. + * + * @param string $armId + * The arm ID. + * @param string $experimentId + * The experiment ID (for cache keying). + * + * @return string + * Human-readable label (node title) or the original arm ID. + */ + protected function resolveArmLabel(string $armId, string $experimentId): string { + $cacheKey = $experimentId . ':' . $armId; + + // Return cached label if available. + if (isset($this->armLabelCache[$cacheKey])) { + return $this->armLabelCache[$cacheKey]; + } + + // If arm_id is numeric, try to resolve as node title. + // Note: Only node entities are currently supported. + if (is_numeric($armId)) { + try { + $node = $this->entityTypeManager->getStorage('node')->load((int) $armId); + if ($node) { + $label = $node->label(); + $this->armLabelCache[$cacheKey] = $label; + return $label; + } + } + catch (\Exception $e) { + // Fall through to return arm_id. + } + } + + return $armId; + } + + /** + * Groups snapshot data by time period. + * + * This method provides database-agnostic date grouping by processing + * raw snapshot data in PHP instead of using MySQL-specific DATE_FORMAT. + * + * @param array $rawResults + * Raw snapshot results with turns, rewards, created fields. + * @param string $period + * Period type: 'daily', 'weekly', or 'monthly'. + * @param int $maxPeriods + * Maximum number of periods to return. + * + * @return array + * Associative array keyed by period string with aggregated data. + */ + protected function groupSnapshotsByPeriod(array $rawResults, string $period, int $maxPeriods): array { + $grouped = []; + + foreach ($rawResults as $row) { + $timestamp = (int) $row->created; + + // Generate period key based on period type. + $periodKey = match ($period) { + 'daily' => date('Y-m-d', $timestamp), + 'monthly' => date('Y-m', $timestamp), + default => date('Y', $timestamp) . '-W' . date('W', $timestamp), + }; + + if (!isset($grouped[$periodKey])) { + $grouped[$periodKey] = [ + 'impressions' => 0, + 'conversions' => 0, + 'period_end' => $timestamp, + ]; + } + + $grouped[$periodKey]['impressions'] += (int) $row->turns; + $grouped[$periodKey]['conversions'] += (int) $row->rewards; + $grouped[$periodKey]['period_end'] = max($grouped[$periodKey]['period_end'], $timestamp); + } + + // Sort by period key and limit. + ksort($grouped); + $grouped = array_slice($grouped, -$maxPeriods, $maxPeriods, TRUE); + + return $grouped; + } + + /** + * Determines experiment status and phase. + * + * @param string $experimentId + * The experiment ID. + * @param int $totalImpressions + * Total impressions. + * + * @return array + * Status info with keys: status, phase, confidence, recommendation. + */ + protected function determineExperimentStatus(string $experimentId, int $totalImpressions): array { + if ($totalImpressions < 100) { + return [ + 'status' => 'insufficient_data', + 'phase' => 'exploration', + 'confidence' => 0, + 'recommendation' => 'Continue collecting data', + ]; + } + + // Get top 2 performers. + $query = $this->database->select('rl_arm_data', 'a'); + $query->fields('a', ['arm_id', 'turns', 'rewards']); + $query->condition('experiment_id', $experimentId); + $query->condition('turns', 50, '>='); + $query->orderBy('rewards', 'DESC'); + $query->range(0, 2); + $topArms = $query->execute()->fetchAll(); + + if (count($topArms) < 2) { + return [ + 'status' => 'active', + 'phase' => 'exploration', + 'confidence' => 0, + 'recommendation' => 'Continue collecting data', + ]; + } + + // Calculate confidence that top arm is better than second. + $top = $topArms[0]; + $second = $topArms[1]; + + $topRate = $top->turns > 0 ? $top->rewards / $top->turns : 0; + $secondRate = $second->turns > 0 ? $second->rewards / $second->turns : 0; + + // Simple confidence estimation based on sample sizes and rate difference. + $pooledRate = ($top->rewards + $second->rewards) / ($top->turns + $second->turns); + $se = sqrt($pooledRate * (1 - $pooledRate) * (1 / $top->turns + 1 / $second->turns)); + $zScore = $se > 0 ? abs($topRate - $secondRate) / $se : 0; + + // Convert z-score to approximate confidence. + $confidence = min(0.99, 0.5 + 0.5 * (1 - exp(-$zScore * $zScore / 2))); + + $phase = 'exploration'; + if ($confidence > 0.8) { + $phase = 'exploitation'; + } + elseif ($confidence > 0.5) { + $phase = 'learning'; + } + + $status = $confidence > 0.95 ? 'conclusive' : 'active'; + + $recommendation = match (TRUE) { + $confidence > 0.95 => 'Ready to conclude - implement winner', + $confidence > 0.8 => 'Strong signal - continue monitoring', + $confidence > 0.5 => 'Learning in progress', + default => 'Continue collecting data', + }; + + return [ + 'status' => $status, + 'phase' => $phase, + 'confidence' => round($confidence, 2), + 'recommendation' => $recommendation, + ]; + } + + /** + * Estimates statistical confidence for an arm. + * + * @param int $conversions + * Number of conversions. + * @param int $impressions + * Number of impressions. + * + * @return float + * Confidence estimate (0-1). + */ + protected function estimateConfidence(int $conversions, int $impressions): float { + if ($impressions < 30) { + return 0; + } + + // Use Wilson score interval width as proxy for confidence. + $p = $conversions / $impressions; + $z = 1.96; + $denominator = 1 + $z * $z / $impressions; + $center = ($p + $z * $z / (2 * $impressions)) / $denominator; + $spread = $z * sqrt(($p * (1 - $p) + $z * $z / (4 * $impressions)) / $impressions) / $denominator; + + // Narrower interval = higher confidence. + $intervalWidth = 2 * $spread; + $confidence = max(0, min(1, 1 - $intervalWidth * 2)); + + return round($confidence, 2); + } + + /** + * Fallback trends when no snapshots available. + * + * @param string $experimentId + * The experiment ID. + * @param string $period + * The period type. + * @param int $periods + * Number of periods. + * + * @return array + * Trends data with current data only. + */ + protected function getTrendsFallback(string $experimentId, string $period, int $periods): array { + $arms = $this->getArmsData($experimentId); + $totalImpressions = array_sum(array_column($arms, 'turns')); + $totalConversions = array_sum(array_column($arms, 'rewards')); + $rate = $totalImpressions > 0 ? round($totalConversions * 100 / $totalImpressions, 2) : 0; + + return [ + 'experiment_id' => $experimentId, + 'period' => $period, + 'periods_returned' => 1, + 'data' => [ + [ + 'period' => 'current', + 'impressions' => $totalImpressions, + 'conversions' => $totalConversions, + 'rate' => $rate, + 'change_pct' => NULL, + ], + ], + 'analysis' => [ + 'trend_direction' => 'insufficient_data', + 'first_period_rate' => $rate, + 'last_period_rate' => $rate, + 'overall_change_pct' => 0, + 'note' => 'Historical snapshots not available. Enable event logging for trend analysis.', + ], + ]; + } + +} diff --git a/src/Service/RlAnalyzerInterface.php b/src/Service/RlAnalyzerInterface.php new file mode 100644 index 0000000..26a39b8 --- /dev/null +++ b/src/Service/RlAnalyzerInterface.php @@ -0,0 +1,115 @@ +turns and ->rewards - * @return array scores keyed by blend id + * @param array $arms_data + * Objects with ->turns and ->rewards. + * + * @return array + * Scores keyed by blend id. */ public function calculateThompsonScores(array $arms_data): array { $scores = []; foreach ($arms_data as $id => $arm) { - $alpha = $arm->rewards + 1; // good ratings + 1 - $beta = ($arm->turns - $arm->rewards) + 1; // bad ratings + 1 + // Good ratings + 1. + $alpha = $arm->rewards + 1; + // Bad ratings + 1. + $beta = ($arm->turns - $arm->rewards) + 1; $scores[$id] = $this->randBeta($alpha, $beta); } return $scores; } - /** Pick the blend with the highest score. */ + /** + * Pick the blend with the highest score. + */ public function selectBestArm(array $scores) { return $scores ? array_keys($scores, max($scores))[0] : NULL; } /*───────────────────── PRIVATE HELPERS ─────────────────────*/ - /** Draw Beta(α,β) by dividing two Gamma draws. */ + /** + * Draw Beta(α,β) by dividing two Gamma draws. */ private function randBeta(int $alpha, int $beta): float { $x = $this->randGamma($alpha); $y = $this->randGamma($beta); @@ -103,21 +111,25 @@ private function randGamma(float $k): float { } /* ----- Case k ≥ 1 --------------------------------------------- */ - $d = $k - 1.0 / 3.0; // shifts the shape - $c = 1.0 / sqrt(9.0 * $d); // scales the normal draw + // Shifts the shape. + $d = $k - 1.0 / 3.0; + // Scales the normal draw. + $c = 1.0 / sqrt(9.0 * $d); - while (true) { + while (TRUE) { /* Step 1: Z ~ N(0,1) */ $z = $this->z(); /* Step 2: candidate V; (1 + cZ) might be negative if Z < −1/c */ $v = pow(1.0 + $c * $z, 3); - if ($v <= 0.0) { // invalid candidate → try again + // Invalid candidate → try again. + if ($v <= 0.0) { continue; } - $u = $this->u(); // U ~ Uniform(0,1) for accept/reject + // U ~ Uniform(0,1) for accept/reject. + $u = $this->u(); /* Step 3a: FAST acceptance (“squeeze” region) * * Inequality derived in the paper ensures we are safely inside * @@ -138,13 +150,15 @@ private function randGamma(float $k): float { /*──────────── RNG helpers (uniform & normal) ──────────────*/ - /** Uniform(0,1) using PHP’s cryptographic RNG. */ + /** + * Uniform(0,1) using PHP’s cryptographic RNG. */ private function u(): float { return random_int(1, PHP_INT_MAX - 1) / PHP_INT_MAX; } /** * Standard normal N(0,1) via Box-Muller transform. + * * Generates two normals per two uniforms; caches one for speed. */ private function z(): float { @@ -163,8 +177,10 @@ private function z(): float { } while ($s >= 1.0 || $s == 0.0); $factor = sqrt(-2.0 * log($s) / $s); - $cache = $u1 * $factor; // save one normal for next call - return $u2 * $factor; // return the other + // Save one normal for next call. + $cache = $u1 * $factor; + // Return the other. + return $u2 * $factor; } } diff --git a/src/Storage/ExperimentDataStorage.php b/src/Storage/ExperimentDataStorage.php index 38ea853..f9684c9 100644 --- a/src/Storage/ExperimentDataStorage.php +++ b/src/Storage/ExperimentDataStorage.php @@ -31,8 +31,8 @@ public function __construct(Connection $database) { */ public function recordTurn($experiment_uuid, $arm_id) { $timestamp = \Drupal::time()->getRequestTime(); - - // Update arm data + + // Update arm data. $this->database->merge('rl_arm_data') ->key(['experiment_uuid' => $experiment_uuid, 'arm_id' => $arm_id]) ->fields([ @@ -44,7 +44,7 @@ public function recordTurn($experiment_uuid, $arm_id) { ->expression('updated', ':timestamp', [':timestamp' => $timestamp]) ->execute(); - // Update total turns + // Update total turns. $this->database->merge('rl_experiment_totals') ->key(['experiment_uuid' => $experiment_uuid]) ->fields([ @@ -71,7 +71,7 @@ public function recordTurns($experiment_uuid, array $arm_ids) { */ public function recordReward($experiment_uuid, $arm_id) { $timestamp = \Drupal::time()->getRequestTime(); - + $this->database->merge('rl_arm_data') ->key(['experiment_uuid' => $experiment_uuid, 'arm_id' => $arm_id]) ->fields([ @@ -82,8 +82,8 @@ public function recordReward($experiment_uuid, $arm_id) { ->expression('rewards', 'rewards + :inc', [':inc' => 1]) ->expression('updated', ':timestamp', [':timestamp' => $timestamp]) ->execute(); - - // Also update experiment totals timestamp + + // Also update experiment totals timestamp. $this->database->merge('rl_experiment_totals') ->key(['experiment_uuid' => $experiment_uuid]) ->fields([ @@ -131,4 +131,4 @@ public function getTotalTurns($experiment_uuid) { return $result ? (int) $result : 0; } -} \ No newline at end of file +} diff --git a/src/Storage/ExperimentDataStorageInterface.php b/src/Storage/ExperimentDataStorageInterface.php index 4011b35..d6b116b 100644 --- a/src/Storage/ExperimentDataStorageInterface.php +++ b/src/Storage/ExperimentDataStorageInterface.php @@ -72,4 +72,4 @@ public function getAllArmsData($experiment_uuid); */ public function getTotalTurns($experiment_uuid); -} \ No newline at end of file +}