Add Analytics API service and Drush commands for AI integration

[jjroelofs]

Summary

Adds a service-based analytics API (rl.analyzer) that enables both Drush commands and other Drupal modules to access experiment performance data, insights, and recommendations.

Architecture:

RlAnalyzerInterface (contract)
       ↓
  RlAnalyzer (service - all business logic)
       ↓
  ┌────┴────┐
Drush     Other modules
Commands  (via dependency injection)

Features

Service API (rl.analyzer)

• listExperiments() - All experiments with summary stats
• getStatus($experimentId) - Detailed status with confidence levels
• getPerformance($experimentId, $limit) - Arm data with human-readable labels
• getTrends($experimentId, $period, $periods) - Historical analysis
• export($experimentId, $includeSnapshots) - Full data export

Drush Commands

• rl:list - List all experiments
• rl:status <experiment> - Experiment status
• rl:performance <experiment> - Arm performance
• rl:trends <experiment> - Historical trends
• rl:analyze <experiment> - Full analysis with recommendations
• rl:export <experiment> - Complete data export

Key Capabilities

• Human-readable labels - Entity IDs resolved to titles (node titles, etc.)
• Pre-computed insights - vs_average, confidence, trend direction
• JSON/YAML output - Structured data for AI consumption
• Actionable recommendations - "Ready to conclude", "Continue monitoring", etc.

Usage Examples

# List all experiments
drush rl:list --format=json

# Get detailed status
drush rl:status ab_test_button_color --format=yaml

# Get top performers with resolved labels
drush rl:performance ai_sorting-help_center_categories-block_1 --limit=10

# Full AI-friendly analysis
drush rl:analyze my_experiment --format=json

// Other modules can inject the service
$analyzer = \Drupal::service('rl.analyzer');
$performance = $analyzer->getPerformance('my_experiment', limit: 10);

Test Plan

• Test rl:list command with table and JSON output
• Test rl:status with YAML output
• Test rl:performance with entity label resolution
• Test rl:trends with historical data
• Test rl:analyze with recommendations
• Test rl:export with and without snapshots
• Verify browser charts still work
• GitHub PR checks pass

Closes #25

[jjroelofs]

Code Review: Analytics API Service and Drush Commands

Overall this is a well-structured PR that follows Drupal best practices. The service-based architecture with a clean interface is the right approach for enabling both Drush commands and programmatic access from other modules.

✅ Strengths

1. Clean Architecture - The RlAnalyzerInterface defines a clear contract, and RlAnalyzer encapsulates all business logic. Drush commands are thin wrappers as intended.

2. Good Documentation - PHPDoc blocks are thorough with parameter types, return types, and descriptions of array structures.

3. Drupal Coding Standards - Proper use of declare(strict_types=1), PHP 8 constructor property promotion, and named arguments.

4. AI-Friendly Design - JSON/YAML output with pre-computed insights (vs_average, confidence, trend_direction) and human-readable labels makes this suitable for AI consumption.

5. Drush Best Practices - Uses PHP 8 attributes (#[CLI\Command], #[CLI\FieldLabels]), proper RowsOfFields return types for tabular data, and good --format support.

---

🔍 Observations / Minor Issues

1. SQL Compatibility - DATE_FORMAT (RlAnalyzer.php:239)

$query->addExpression("DATE_FORMAT(FROM_UNIXTIME(s.created), '{$dateFormat}')", 'period_key');

DATE_FORMAT is MySQL-specific. If the module needs to support PostgreSQL or SQLite, consider using database-agnostic date functions or Drupal's Connection::condition() with date handling.

Impact: Only affects sites using non-MySQL databases. Low priority if MySQL is the only supported DB.

---

2. Exception Type (RlAnalyzerInterface.php)

The interface documents @throws \InvalidArgumentException but for a "not found" scenario, a more semantic exception like \Drupal\rl\Exception\ExperimentNotFoundException (which already exists in the codebase) would be more appropriate.

This allows calling code to catch specific "not found" cases vs. other argument validation errors.

---

3. Entity Loading in Loop (RlAnalyzer.php:441-456)

protected function resolveArmLabel(string $armId, string $experimentId): string {
  if (is_numeric($armId)) {
    $node = $this->entityTypeManager->getStorage('node')->load((int) $armId);
    // ...
  }
}

When called for many arms in getPerformance(), this results in N+1 queries. For better performance, consider batch-loading entities:

// Collect all numeric arm IDs first
$nodeIds = array_filter($armIds, 'is_numeric');
$nodes = $this->entityTypeManager->getStorage('node')->loadMultiple($nodeIds);

Impact: Performance degradation on experiments with many arms (50+). Low priority for typical use cases.

---

4. Hardcoded Entity Type (RlAnalyzer.php:445)

The label resolver only handles nodes. If experiments can have arms pointing to taxonomy terms, media, or other entities, consider:

• Parsing the arm_id format to detect entity type (e.g., node:123, term:456)
• Or documenting that only node entities are supported

---

5. Division by Zero Guard (RlAnalyzer.php:506)

$se = sqrt($pooledRate * (1 - $pooledRate) * (1 / $top->turns + 1 / $second->turns));

While $top->turns and $second->turns are filtered to be >= 50 via the query, if pooledRate is 0 or 1, se becomes 0, leading to a potential divide-by-zero on line 507. Currently handled by the ternary, but worth noting.

---

💡 Suggestions (Non-blocking)

1. Consider adding getConfig() method - The CLAUDE.md plan mentions this but it's not implemented. Could return experiment configuration/metadata for debugging.

2. Caching - For high-traffic sites, consider caching listExperiments() results with cache tags that invalidate on arm data changes.

3. Drush command rl:analyze - The combined status+performance command is useful. Consider making it the default suggested command in documentation since it provides the most comprehensive view.

---

✅ Summary

Approve with minor suggestions. The implementation is solid and ready for merge. The observations above are mostly edge cases or future improvements rather than blocking issues.

The clean separation between interface → service → Drush commands is exactly right, and the output formats are well-suited for both human and AI consumption.